ServicePlan¶

Service plan is set of basic services and resources assigned with definite pricing. Services plans are offered for sale to customers.

In this document:

Schema
Properties
Relationship
Custom Operations
Structures
Examples

Schema ¶

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "ServicePlan",
  "id": "http://www.odin.com/billing/ServicePlan/1.1",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "relations": {
    "vendor": {
      "type": "http://parallels.com/aps/types/pa/account",
      "required": true
    },
    "serviceTemplate": {
      "type": "http://parallels.com/aps/types/pa/serviceTemplate",
      "backrel": false
    },
    "category": {
      "type": "http://www.odin.com/billing/ServicePlanCategory/1.0",
      "required": true
    },
    "serviceTerms": {
      "type": "http://www.odin.com/billing/ServiceTerms/1.0",
      "required": true
    },
    "resources": {
      "type": "http://www.odin.com/billing/Resource/1.3",
      "collection": true
    },
    "parentServicePlan": {
      "type": "http://www.odin.com/billing/ServicePlan/1.1"
    }
  },
  "properties": {
    "planId": {
      "type": "integer"
    },
    "name": {
      "type": "http://aps-standard.org/types/core/i18n/1.3#MLString",
      "required": true
    },
    "shortDescription": {
      "type": "http://aps-standard.org/types/core/i18n/1.3#MLString",
      "required": true
    },
    "longDescription": {
      "type": "http://aps-standard.org/types/core/i18n/1.3#MLString",
      "required": true
    },
    "publication": {
      "type": "ServicePlanPublication"
    },
    "subscriptionPeriods": {
      "type": "array",
      "items": {
        "type": "ServicePlanSubscriptionPeriod"
      }
    },
    "subscriptionPeriodResourceRates": {
      "type": "array",
      "items": {
        "type": "ServicePlanSubscriptionPeriodResourceRate"
      }
    },
    "resourceRates": {
      "type": "array",
      "items": {
        "type": "ServicePlanResourceRate"
      }
    },
    "billingTerms": {
      "type": "ServicePlanBillingTerms"
    }
  },
  "operations": {
    "getPlanSwitches": {
      "path": "/planSwitches",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "ServicePlanSubscriptionPeriodSwitches"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "getPlanPeriodSwitches": {
      "path": "/planPeriodSwitches",
      "verb": "POST",
      "response": {
        "type": "array",
        "items": {
          "type": "ServicePlanSubscriptionPeriodSwitch"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "referrer": true
      },
      "parameters": {
        "period": {
          "kind": "body",
          "type": "SubscriptionPeriod",
          "required": true
        }
      }
    },
    "getPlanSwitchPolicies": {
      "path": "/planSwitchPaths",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "ServicePlanSwitchPolicy"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    }
  },
  "structures": {
    "ServicePlanPublication": {
      "type": "object",
      "properties": {
        "published": {
          "type": "boolean",
          "required": true
        }
      }
    },
    "ServicePlanSubscriptionPeriod": {
      "type": "object",
      "properties": {
        "autoRenewalPeriod": {
          "type": "SubscriptionPeriod"
        },
        "numberOfBillingPeriods": {
          "type": "integer",
          "readonly": true
        },
        "trial": {
          "type": "boolean"
        },
        "defaultPeriod": {
          "type": "boolean"
        },
        "fees": {
          "type": "ServicePlanSubscriptionPeriodFees",
          "required": true
        },
        "refund": {
          "type": "ServicePlanSubscriptionPeriodRefund",
          "required": true
        },
        "sortOrder": {
          "type": "integer"
        },
        "active": {
          "type": "boolean"
        }
      }
    },
    "SubscriptionPeriod": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "enum": [
            "DAYS",
            "MONTHS",
            "YEARS"
          ]
        },
        "duration": {
          "type": "integer"
        }
      }
    },
    "ServicePlanSubscriptionPeriodFees": {
      "type": "object",
      "properties": {
        "setup": {
          "type": "ServicePlanSubscriptionPeriodFeeSetup"
        },
        "recurring": {
          "type": "ServicePlanSubscriptionPeriodFeeRecurring"
        },
        "renewal": {
          "type": "ServicePlanSubscriptionPeriodFeeRenewal"
        },
        "deposit": {
          "type": "ServicePlanSubscriptionPeriodFeeDeposit"
        }
      }
    },
    "ServicePlanSubscriptionPeriodFeeSetup": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "showZeroPrice": {
          "type": "boolean"
        }
      }
    },
    "Currency": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string"
        },
        "code": {
          "type": "string"
        }
      }
    },
    "ServicePlanSubscriptionPeriodFeeRecurring": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "showZeroPrice": {
          "type": "boolean"
        }
      }
    },
    "ServicePlanSubscriptionPeriodFeeRenewal": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "showZeroPrice": {
          "type": "boolean"
        }
      }
    },
    "ServicePlanSubscriptionPeriodFeeDeposit": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "showZeroPrice": {
          "type": "boolean"
        }
      }
    },
    "ServicePlanSubscriptionPeriodRefund": {
      "type": "object",
      "properties": {
        "nonRefundableAmount": {
          "type": "Currency",
          "required": true
        },
        "fullRefundPeriodInDays": {
          "type": "integer"
        },
        "afterRefundPeriod": {
          "type": "string",
          "enum": [
            "NO",
            "RECURRING"
          ]
        }
      }
    },
    "ServicePlanSubscriptionPeriodResourceRate": {
      "type": "object",
      "properties": {
        "autoRenewalPeriod": {
          "type": "SubscriptionPeriod"
        },
        "resourceId": {
          "type": "string",
          "required": true
        },
        "fees": {
          "type": "ServicePlanResourceRateFees"
        },
        "publication": {
          "type": "ServicePlanResourceRatePublication"
        }
      }
    },
    "ServicePlanResourceRateFees": {
      "type": "object",
      "properties": {
        "setup": {
          "type": "ServicePlanResourceRateFeeSetup"
        },
        "recurring": {
          "type": "ServicePlanResourceRateFeeRecurring"
        },
        "overuse": {
          "type": "ServicePlanResourceRateFeeOveruse"
        },
        "setupTiers": {
          "type": "array",
          "items": {
            "type": "FeeTier"
          }
        },
        "recurringTiers": {
          "type": "array",
          "items": {
            "type": "FeeTier"
          }
        },
        "recurringPriceModel": {
          "type": "string",
          "enum": [
            "FLAT",
            "TIERED",
            "VOLUME",
            "VOLUME_ORDER",
            "VOLUME_RESOURCE_AGGREGATED"
          ],
          "enumTitles": [
            "Flat price",
            "Tiered pricing at subscription level",
            "Volume pricing at subscription level",
            "Volume pricing at order level",
            "Multi-resource volume pricing at order and subscription levels"
          ]
        },
        "setupPriceModel": {
          "type": "string",
          "enum": [
            "FLAT",
            "TIERED",
            "VOLUME",
            "VOLUME_ORDER",
            "VOLUME_RESOURCE_AGGREGATED"
          ],
          "enumTitles": [
            "Flat price",
            "Tiered pricing at subscription level",
            "Volume pricing at subscription level",
            "Volume pricing at order level",
            "Multi-resource volume pricing at order and subscription levels"
          ]
        },
        "overusePriceModel": {
          "type": "string",
          "enum": [
            "FLAT",
            "TIERED",
            "VOLUME",
            "VOLUME_ORDER",
            "VOLUME_RESOURCE_AGGREGATED"
          ],
          "enumTitles": [
            "Flat price",
            "Tiered pricing at subscription level",
            "Volume pricing at subscription level",
            "Volume pricing at order level",
            "Multi-resource volume pricing at order and subscription levels"
          ]
        },
        "overuseTiers": {
          "type": "array",
          "items": {
            "type": "FeeTier"
          }
        }
      }
    },
    "ServicePlanResourceRateFeeSetup": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "showZeroPrice": {
          "type": "boolean"
        },
        "chargePerUnit": {
          "type": "boolean"
        }
      }
    },
    "ServicePlanResourceRateFeeRecurring": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "showZeroPrice": {
          "type": "boolean"
        },
        "chargePerUnit": {
          "type": "boolean"
        }
      }
    },
    "ServicePlanResourceRateFeeOveruse": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "showZeroPrice": {
          "type": "boolean"
        }
      }
    },
    "FeeTier": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "lowerLimit": {
          "type": "number"
        },
        "ratingAttributes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "discountedPrices": {
          "type": "array",
          "items": {
            "type": "DiscountTier"
          }
        }
      }
    },
    "DiscountTier": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "ratingAttribute": {
          "type": "string"
        },
        "priceLevelHint": {
          "type": "string"
        }
      }
    },
    "ServicePlanResourceRatePublication": {
      "type": "object",
      "properties": {
        "store": {
          "type": "ServicePlanResourceRatePublicationStore"
        }
      }
    },
    "ServicePlanResourceRatePublicationStore": {
      "type": "object",
      "properties": {
        "description": {
          "type": "http://aps-standard.org/types/core/i18n/1.3#MLString"
        },
        "priceText": {
          "type": "http://aps-standard.org/types/core/i18n/1.3#MLString"
        }
      }
    },
    "ServicePlanResourceRate": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "required": true
        },
        "showInStore": {
          "type": "boolean"
        },
        "measurable": {
          "type": "boolean"
        },
        "showInCustomerPanel": {
          "type": "boolean"
        },
        "sortNumber": {
          "type": "integer"
        },
        "fees": {
          "type": "ServicePlanResourceRateFees"
        },
        "publication": {
          "type": "ServicePlanResourceRatePublication"
        },
        "units": {
          "type": "ServicePlanResourceRateUnits"
        },
        "display": {
          "type": "Display"
        },
        "modifyInTrial": {
          "type": "boolean"
        },
        "published": {
          "type": "boolean"
        },
        "mpn": {
          "type": "string"
        }
      }
    },
    "ServicePlanResourceRateUnits": {
      "type": "object",
      "properties": {
        "included": {
          "type": "number",
          "required": true
        },
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        }
      }
    },
    "Display": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "DEFAULT",
            "SLIDER"
          ]
        },
        "incrementValue": {
          "type": "integer"
        },
        "allowedValuesList": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        }
      }
    },
    "ServicePlanBillingTerms": {
      "type": "object",
      "properties": {
        "model": {
          "type": "string",
          "enum": [
            "CHARGE_BEFORE_BILLING_PERIOD",
            "CHARGE_AFTER_BILLING_PERIOD",
            "CHARGE_BEFORE_SUBSCRIPTION_PERIOD",
            "CHARGE_EXTERNAL_RATING",
            "CHARGE_ON_PURCHASE"
          ]
        },
        "pricingModel": {
          "type": "string",
          "enum": [
            "PM_FIXED_PRICE",
            "PM_COST_MARKUP"
          ]
        },
        "isScheduledOrdersAllowed": {
          "type": "boolean"
        },
        "isExpDateAlignedWithEndOfMonth": {
          "type": "boolean"
        },
        "isExpDateAlignedWithSubscr": {
          "type": "boolean"
        },
        "billingPeriodAlignment": {
          "type": "string",
          "default": "SUBSCRIPTION_PERIOD_START",
          "enum": [
            "SUBSCRIPTION_PERIOD_START",
            "SUBSCRIPTION_PERIOD_EXPIRATION"
          ]
        },
        "cotermingPossibility": {
          "type": "string",
          "default": "RESTRICTED",
          "enum": [
            "RESTRICTED",
            "ALLOWED",
            "FIXED_DATE_FROM_VENDOR"
          ]
        },
        "period": {
          "type": "ServicePlanBillingPeriod",
          "required": true
        },
        "recurringPricesEvery": {
          "type": "string",
          "enum": [
            "BILLING_PERIOD",
            "MONTH"
          ]
        },
        "autorenewal": {
          "type": "ServicePlanAutorenewal"
        }
      }
    },
    "ServicePlanBillingPeriod": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "enum": [
            "STATEMENT_DAY",
            "MONTHS",
            "YEARS"
          ]
        },
        "duration": {
          "type": "integer"
        }
      }
    },
    "ServicePlanAutorenewal": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "DISABLED",
            "BEFORE_EXPIRATION_DATE",
            "ON_LAST_STATEMENT_DATE"
          ]
        },
        "days": {
          "type": "integer"
        }
      }
    },
    "ServicePlanSubscriptionPeriodSwitch": {
      "type": "object",
      "properties": {
        "target": {
          "type": "SwitchTarget"
        },
        "switchFee": {
          "type": "Fee"
        },
        "switchType": {
          "type": "string",
          "enum": [
            "MANUAL",
            "AUTOMATIC"
          ]
        },
        "switchFeeType": {
          "type": "string",
          "enum": [
            "NONE",
            "FIXED",
            "REMAININGS",
            "CUSTOM"
          ]
        },
        "billingPolicy": {
          "type": "string",
          "enum": [
            "PRORATE_STARTING_NEW_SUBSCRIPTION_PERIOD",
            "PRORATE_KEEPING_EXP_DATE",
            "PRORATE_CHOOSE_OPTION",
            "PRORATE_REFUND",
            "NO_REFUND"
          ]
        },
        "whenEffective": {
          "type": "string",
          "enum": [
            "IMMEDIATELY",
            "NEXT_BILLING_PERIOD",
            "NEXT_SUBSCRIPTION_PERIOD"
          ]
        },
        "operation": {
          "type": "string",
          "enum": [
            "RENEW",
            "CHANGE",
            "CANCELLATION"
          ]
        },
        "fullRefundPeriod": {
          "type": "integer"
        },
        "resourceMappings": {
          "type": "array",
          "items": {
            "type": "ResourceMapping"
          }
        },
        "switchPolicies": {
          "type": "SwitchPolicies"
        }
      }
    },
    "SwitchTarget": {
      "type": "object",
      "properties": {
        "planId": {
          "type": "string"
        },
        "period": {
          "type": "SubscriptionPeriod"
        }
      }
    },
    "Fee": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "description": {
          "type": "http://aps-standard.org/types/core/i18n/1.3#MLString"
        }
      }
    },
    "ResourceMapping": {
      "type": "object",
      "properties": {
        "fromResourceId": {
          "type": "string"
        },
        "toResourceId": {
          "type": "string"
        }
      }
    },
    "SwitchPolicies": {
      "type": "object",
      "properties": {
        "immediateSwitchAllowed": {
          "type": "boolean"
        },
        "partialSwitchAllowed": {
          "type": "boolean"
        },
        "subsStartDateAfterSwitch": {
          "type": "string",
          "default": "UST_UPGRADE_DATE",
          "enum": [
            "UST_OLD_START_DATE",
            "UST_UPGRADE_DATE"
          ]
        },
        "subsPeriodChange": {
          "type": "string",
          "default": "ANY_AVAILABLE",
          "enum": [
            "NOT_ALLOWED",
            "ANY_AVAILABLE",
            "SAME_OR_LONGER"
          ]
        },
        "downSizeAllowed": {
          "type": "boolean"
        },
        "upsizeAllowed": {
          "type": "boolean"
        }
      }
    },
    "ServicePlanSubscriptionPeriodSwitches": {
      "type": "object",
      "properties": {
        "sourcePeriod": {
          "type": "SubscriptionPeriod"
        },
        "upgrades": {
          "type": "array",
          "items": {
            "type": "ServicePlanSubscriptionPeriodSwitch"
          }
        }
      }
    },
    "ServicePlanSwitch": {
      "type": "object",
      "properties": {
        "planId": {
          "type": "integer"
        },
        "name": {
          "type": "MultiLangString"
        },
        "period": {
          "type": "SubscriptionPeriod"
        }
      }
    },
    "MultiLangString": {
      "type": "object"
    },
    "ServicePlanSwitchPolicy": {
      "type": "object",
      "properties": {
        "servicePlanSwitch": {
          "type": "ServicePlanSwitch"
        },
        "policies": {
          "type": "SwitchPolicies"
        }
      }
    }
  }
}

The APS type is used to manage a collection of APS resources. To get a list of resources from that collection, use the following API call:

GET  /aps/2/collections/service-plans?<RQL-filter>

Properties ¶

NAME	TYPE	ATTRIBUTES	DESCRIPTION
planId	Integer	Not Required
name	I18n	Required	Service plan’s name
shortDescription	I18n	Required	Service plan’s short description
longDescription	I18n	Required	Service plan’s long description
publication	ServicePlanPublication	Not Required	Service plan’s publication information
subscriptionPeriods	Array of ServicePlanSubscriptionPeriod	Not Required	List of plan’s subscription periods
subscriptionPeriodResourceRates	Array of ServicePlanSubscriptionPeriodResourceRate	Not Required	List of subscription’s resource rates.
resourceRates	Array of ServicePlanResourceRate	Not Required	List of plan’s subscription rates
billingTerms	ServicePlanBillingTerms	Not Required	Billing terms for service plan

Relationship ¶

NAME	TYPE	REQUIRED	DESCRIPTION
vendor	PAAccount	Yes	Vendor - owner of this service plan
serviceTemplate	PAServiceTemplate	No	OSS service template
category	ServicePlanCategory	Yes	Service plan category
serviceTerms	ServiceTerms	Yes	Service terms for service plan
resources	Collection of BSSResource	No	Collection of resources for this service plan
parentServicePlan	ServicePlan	No	Parent plan details

Custom Operations ¶

OPERATION	VERB	PATH	RETURNS	Description
getPlanSwitches	GET	/planSwitches	A collection of plan periods with possible upgrades	Get all possible upgrades for Service Plan
getPlanPeriodSwitches	POST	/planPeriodSwitches	A collection of upgrades for the plan period	Get possible upgrades for a specified plan period
getPlanSwitchPolicies	GET	/planSwitchPaths	A collection of allowance policies	Get allowance policies for all existing upgrades of a Service Plan

getPlanSwitches¶

HTTP Request

GET /aps/2/resources/{aps-id}/planSwitches

Description

Get all possible upgrades for Service Plan

Returns

A collection of plan periods with possible upgrades

getPlanPeriodSwitches¶

HTTP Request

POST /aps/2/resources/{aps-id}/planPeriodSwitches

Description

Get possible upgrades for a specified plan period

Parameters

PARAMETER	TYPE	DESCRIPTION
period	SubscriptionPeriod	a plan period to get upgrades for

Returns

A collection of upgrades for the plan period

getPlanSwitchPolicies¶

HTTP Request

GET /aps/2/resources/{aps-id}/planSwitchPaths

Description

Get allowance policies for all existing upgrades of a Service Plan

Returns

A collection of allowance policies

Structures ¶

ServicePlanPublication¶

Service plan’s publication information.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
published	Boolean	Required		Publishing flag for service plan

ServicePlanSubscriptionPeriod¶

Service Plan period for a service plan. Contains duration and corresponding fees for subscription and optionally fees for corresponding resources in a service plan.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
autoRenewalPeriod	SubscriptionPeriod	Not Required	Service Plan auto renewal period - period in which subscription will be renewed.
numberOfBillingPeriods	Integer	Not Required Read Only	Number of billing periods in subscription period.
trial	Boolean	Not Required	Flag for trial subscription.
defaultPeriod	Boolean	Not Required	Flag for default subscription period.
fees	ServicePlanSubscriptionPeriodFees	Required	Fees for subscription period.
refund	ServicePlanSubscriptionPeriodRefund	Required	Refund info.
sortOrder	Integer	Not Required	Sort order.
active	Boolean	Not Required	Flag for active subscription.

SubscriptionPeriod¶

Subscription period duration and type structure.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
unit	Enum	Not Required		Subscription period unit.
duration	Integer	Not Required		Duration of subscription period.

ServicePlanSubscriptionPeriodFees¶

Fees for ServicePlanSubscriptionPeriod.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
setup	ServicePlanSubscriptionPeriodFeeSetup	Not Required	Setup fee.
recurring	ServicePlanSubscriptionPeriodFeeRecurring	Not Required	Recurring fee.
renewal	ServicePlanSubscriptionPeriodFeeRenewal	Not Required	Renewal fee
deposit	ServicePlanSubscriptionPeriodFeeDeposit	Not Required	Deposit fee

ServicePlanSubscriptionPeriodFeeSetup¶

Subscription period setup fee type.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
price	Currency	Not Required
msrp	Currency	Not Required
showZeroPrice	Boolean	Not Required	Show zero price flag

Currency¶

Basic currency structure.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
value	String	Not Required		Amount.
code	String	Not Required		Currency Code

ServicePlanSubscriptionPeriodFeeRecurring¶

Subscription period recurring fee type.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
price	Currency	Not Required
msrp	Currency	Not Required
showZeroPrice	Boolean	Not Required	Show zero price flag

ServicePlanSubscriptionPeriodFeeRenewal¶

Subscription period renewal fee type.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
price	Currency	Not Required
msrp	Currency	Not Required
showZeroPrice	Boolean	Not Required	Show zero price flag

ServicePlanSubscriptionPeriodFeeDeposit¶

Subscription period deposit fee type.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
price	Currency	Not Required
msrp	Currency	Not Required
showZeroPrice	Boolean	Not Required	Show zero price flag

ServicePlanSubscriptionPeriodRefund¶

Refund info for ServicePlanSubscriptionPeriod.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
nonRefundableAmount	Currency	Required	Non refundable amount of money.
fullRefundPeriodInDays	Integer	Not Required	Full refund period in days.
afterRefundPeriod	Enum	Not Required	After refund period option. After refund period type

ServicePlanSubscriptionPeriodResourceRate¶

Subscription resource rate info for ServicePlanSubscriptionPeriod.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
autoRenewalPeriod	SubscriptionPeriod	Not Required	Service Plan auto renewal period - period in which subscription will be renewed.
resourceId	String	Required	UUID of corresponding BSSResource
fees	ServicePlanResourceRateFees	Not Required	Fees for resource rate
publication	ServicePlanResourceRatePublication	Not Required	Publication information for resource rate

ServicePlanResourceRateFees¶

Fees for ServicePlanResourceRate and ServicePlanSubscriptionPeriodResourceRate.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
setup	ServicePlanResourceRateFeeSetup	Not Required	Setup fee
recurring	ServicePlanResourceRateFeeRecurring	Not Required	Recurring fee
overuse	ServicePlanResourceRateFeeOveruse	Not Required	Overuse fee
setupTiers	Array of FeeTier	Not Required	Setup fee Tier
recurringTiers	Array of FeeTier	Not Required	Recurring fee Tier
recurringPriceModel	Enum	Not Required	Service plan recurring fee price model The price model can be one of the following: `FLAT`: the price per resource unit does not depend on the resource amount purchased in the subscription. `TIERED`: the price per resource unit changes depending on the total resource amount. `VOLUME_SUBSCRIPTION`: the price per resource unit changes depending on the total resource amount. `VOLUME_ORDER`: the price per resource unit changes depending on the total resource amount. `VOLUME_RESOURCE_AGGREGATED`: the price per resource unit changes depending on the amount of group of resources.
setupPriceModel	Enum	Not Required	Service plan setup fee price model The price model can be one of the following: `FLAT`: the price per resource unit does not depend on the resource amount purchased in the subscription. `TIERED`: the price per resource unit changes depending on the total resource amount. `VOLUME_SUBSCRIPTION`: the price per resource unit changes depending on the total resource amount. `VOLUME_ORDER`: the price per resource unit changes depending on the total resource amount. `VOLUME_RESOURCE_AGGREGATED`: the price per resource unit changes depending on the amount of group of resources.
overusePriceModel	Enum	Not Required	Service plan overuse fee price model The price model can be one of the following: `FLAT`: the price per resource unit does not depend on the resource amount purchased in the subscription. `TIERED`: the price per resource unit changes depending on the total resource amount. `VOLUME_SUBSCRIPTION`: the price per resource unit changes depending on the total resource amount. `VOLUME_ORDER`: the price per resource unit changes depending on the total resource amount. `VOLUME_RESOURCE_AGGREGATED`: the price per resource unit changes depending on the amount of group of resources.
overuseTiers	Array of FeeTier	Not Required	Overuse fee Tier

ServicePlanResourceRateFeeSetup¶

Setup fee for ServicePlanResourceRate.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
price	Currency	Not Required
msrp	Currency	Not Required
showZeroPrice	Boolean	Not Required	Show zero price flag
chargePerUnit	Boolean	Not Required	Charge per unit flag

ServicePlanResourceRateFeeRecurring¶

Recurring fee for ServicePlanResourceRate.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
price	Currency	Not Required
msrp	Currency	Not Required
showZeroPrice	Boolean	Not Required	Show zero price flag
chargePerUnit	Boolean	Not Required	Charge per unit flag

ServicePlanResourceRateFeeOveruse¶

Overuse fee for ServicePlanResourceRate.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
price	Currency	Not Required
msrp	Currency	Not Required
showZeroPrice	Boolean	Not Required	Show zero price flag

FeeTier¶

This structure contain information about resource tier limit

NAME	TYPE	ATTRIBUTES
price	Currency	Not Required
msrp	Currency	Not Required
lowerLimit	Number	Not Required
ratingAttributes	Array of String	Not Required
discountedPrices	Array of DiscountTier	Not Required

DiscountTier¶

NAME	TYPE	ATTRIBUTES
price	Currency	Not Required
msrp	Currency	Not Required
ratingAttribute	String	Not Required
priceLevelHint	String	Not Required

ServicePlanResourceRatePublication¶

Publication information for ServicePlanResourceRate and ServicePlanSubscriptionPeriodResourceRate.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
store	ServicePlanResourceRatePublicationStore	Not Required		Store publication information

ServicePlanResourceRatePublicationStore¶

Store publication information for resource.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
description	I18n	Not Required		Description in store.
priceText	I18n	Not Required		Price text.

ServicePlanResourceRate¶

Resource rate info.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
resourceId	String	Required	UUID of corresponding BSSResource.
showInStore	Boolean	Not Required	Flag to show/hide resource in store.
measurable	Boolean	Not Required	Flag indicating that resource is measurable.
showInCustomerPanel	Boolean	Not Required	Flag to show/hide resource in customer panel.
sortNumber	Integer	Not Required	Sort number.
fees	ServicePlanResourceRateFees	Not Required	Fees for resource.
publication	ServicePlanResourceRatePublication	Not Required	Publication information for resource.
units	ServicePlanResourceRateUnits	Not Required	Resource rate units info.
display	Display	Not Required	Resource display type info
modifyInTrial	Boolean	Not Required	Flag to enable/disable resource modification in trial period.
published	Boolean	Not Required	Flag to enable/disable resource publishing.
mpn	String	Not Required	Superseded MPN value. Effective value can be obtained by the following rule: if ServicePlan.resourceRates[].MPN is present then MPN is ServicePlan.resourceRates[].MPN else ServicePlan.resources[ServicePlan.resourceRates[].resourceId].MPN

ServicePlanResourceRateUnits¶

Resource rate units info.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
included	Number	Required	Included resources in service plan.
min	Number	Not Required	Minimum resources in service plan.
max	Number	Not Required	Maximum resources in service plan. -1 for unlimited value.

Display¶

Resource display type info

NAME	TYPE	ATTRIBUTES	DESCRIPTION
type	Enum	Not Required	Display type info Enum containing DisplayType
incrementValue	Integer	Not Required	Increment value info
allowedValuesList	Array of Integer	Not Required	Allowed values in List

ServicePlanBillingTerms¶

Billing terms for ServicePlan.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
model	Enum	Not Required		Billing model Service plan billing model.
pricingModel	Enum	Not Required		Pricing model Service plan pricing model.
isScheduledOrdersAllowed	Boolean	Not Required
isExpDateAlignedWithEndOfMonth	Boolean	Not Required
isExpDateAlignedWithSubscr	Boolean	Not Required
billingPeriodAlignment	Enum	Not Required	SUBSCRIPTION_PERIOD_START
cotermingPossibility	Enum	Not Required	RESTRICTED
period	ServicePlanBillingPeriod	Required		Billing Period
recurringPricesEvery	Enum	Not Required		Period of recurring fees charging Service plan recurring price period type.
autorenewal	ServicePlanAutorenewal	Not Required		Autorenewal period

ServicePlanBillingPeriod¶

Billing period for service plan.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
unit	Enum	Not Required		Service plan billing period’s unit. Service plan billing period unit type.
duration	Integer	Not Required		Duration of billing period.

ServicePlanAutorenewal¶

Service plan autorenewal parameters.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
type	Enum	Not Required		Autorenewal type Service plan autorenewal type.
days	Integer	Not Required		Autorenewal period in days

ServicePlanSubscriptionPeriodSwitch¶

Plan Period switch configuration Possible switches are: - From one Subscription Period to another of the same plan - From one Subscription Period to any Subscription Period of another plan - From one Subscription Period to specific Subscription Period of another plan - Cancellation Switch from one Subscription Period any Subscription Period of another (or the same) plan is specified by non-empty value of target property. Operation to perform a switch is defined by operation property.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
target	SwitchTarget	Not Required	Optional plan period reference to switch to
switchFee	Fee	Not Required	A fee to be charged from a customer for a switch
switchType	Enum	Not Required	A switch type: `MANUAL` - a renew order should be placed at the end of subscription period to renew a subscrition `AUTOMATIC` - a renew order will be placed automatically
switchFeeType	Enum	Not Required	A fee type. Possible values are: `NONE` - no fee will be charged `FIXED` - fixed fee will be charged. Plan upgrade uses this fee type mostly `REMAININGS` - a fee, which is equal to not used part of recurring fee will be charged. Cancellation uses this fee type mostly `CUSTOM` - a fee is calculated using a formula. Cancellation uses this fee type mostly
billingPolicy	Enum	Not Required	A billing term to be used to charge a customer. Possible values are: `PRORATE_STARTING_NEW_SUBSCRIPTION_PERIOD` - an order will start a new subscription period `PRORATE_KEEPING_EXP_DATE` - an order will keep current subscription period `PRORATE_CHOOSE_OPTION` - a user can select `PRORATE_REFUND` - a charge for not used resources will be refunded `NO_REFUND` - a charge for not used resources will not be refunded
whenEffective	Enum	Not Required	An applicability delay. A switch can be applied either on an order date or next billing date or subscription period end. Possible values are: `IMMEDIATELY` - on order date `NEXT_BILLING_PERIOD` - on the next billing date `NEXT_SUBSCRIPTION_PERIOD` - at a subscription period end
operation	Enum	Not Required	A type of operation (order type) to perform a switch. Possible values are: `RENEW` - renew `CHANGE` - change plan/period `CANCELLATION` - cancel a subscription
fullRefundPeriod	Integer	Not Required	An optional value of full refund period
resourceMappings	Array of ResourceMapping	Not Required
switchPolicies	SwitchPolicies	Not Required

SwitchTarget¶

Specifies a target to switch to A target is specified by plan and a subscription period

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
planId	String	Not Required		Aps.id of a ServicePlan resource acting as a target
period	SubscriptionPeriod	Not Required		A subscription period of target plan to switch to

Fee¶

Base fee structure.

NAME	TYPE	ATTRIBUTES
price	Currency	Not Required
msrp	Currency	Not Required
description	I18n	Not Required

ResourceMapping¶

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
fromResourceId	String	Not Required
toResourceId	String	Not Required

SwitchPolicies¶

Switch policies

NAME	TYPE	ATTRIBUTES	DEFAULT
immediateSwitchAllowed	Boolean	Not Required
partialSwitchAllowed	Boolean	Not Required
subsStartDateAfterSwitch	Enum	Not Required	UST_UPGRADE_DATE
subsPeriodChange	Enum	Not Required	ANY_AVAILABLE
downSizeAllowed	Boolean	Not Required
upsizeAllowed	Boolean	Not Required

ServicePlanSubscriptionPeriodSwitches¶

A list of upgrades that are available for specified plan period

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
sourcePeriod	SubscriptionPeriod	Not Required		Source plan period
upgrades	Array of ServicePlanSubscriptionPeriodSwitch	Not Required		A collection of possible upgrades from the specified plan period

ServicePlanSwitch¶

Specifies a target to switch to A target is specified by plan and a subscription period

NAME	TYPE	ATTRIBUTES	DESCRIPTION
planId	Integer	Not Required	BSS id of a ServicePlan resource acting as a target
name	MultiLangString	Not Required	Switch target service plan name
period	SubscriptionPeriod	Not Required	A subscription period of target plan to switch to

MultiLangString¶

ServicePlanSwitchPolicy¶

Specifies allowance policies for a plan switch

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
servicePlanSwitch	ServicePlanSwitch	Not Required
policies	SwitchPolicies	Not Required

Examples ¶

Get all Service Plans¶

The following request must return a list of all service plans available for the requester:

GET /aps/2/collections/service-plans

The response will look like this (details are omitted):

HTTP/1.1 200 OK

[
   {
      "aps": {/* ... */},
      "billingTerms": {/* ... */},
      "resourceRates": [],
      "longDescription": {/* ... */},
      "name": {
         "en_US": "User Management Demo"
      },
      "publication": {/* ... */},
      "shortDescription": {/* ... */},
      "subscriptionPeriods": [],
   },
   {
      "aps": {/* ... */},
      "billingTerms": {/* ... */},
      "resourceRates": [],
      "longDescription": {/* ... */},
      "name": {
         "en_US": "Resource Consumption"
      },
      "publication": {/* ... */},
      "shortDescription": {/* ... */},
      "subscriptionPeriods": [],
   },
   /* ... */
]

Get selected Service Plans¶

It is possible to add RQL filters to narrow the list of service plans, such as the following:

Get all published service plans - the products ready for sale:

GET /aps/2/collections/service-plans?eq(publication.published,true)

Omit service plan details, for example, show only the names in English:
```
GET /aps/2/collections/service-plans?select(name.en_US)
```
Note

Anyway, the response will still contain the aps:{...} section.

Similarly to the previous, show only the names and subscription periods:

GET /aps/2/collections/service-plans?select(name.en_US,subscriptionPeriods)

Similarly, show the names and resource rates:

GET /aps/2/collections/service-plans?select(name.en_US,resourceRates)

Get Service Plan Details¶

If the management system knows the APS ID of a service plan, it can request its full JSON representation.

GET /aps/2/resources/314dac37-d3bd-4978-b05e-ba4658514485

The response will look like this (some details are omitted):

HTTP/1.1 200 OK

{
   "aps": {/* ... */},
   "name": {/* ... */},
   "shortDescription": {/* ... */},
   "longDescription": {/* ... */},
   "subscriptionPeriods": [
      {
         "autoRenewalPeriod": {/* ... */},
         "numberOfBillingPeriods": 1,
         "trial": false,
         "defaultPeriod": false,
         "fees": {
            "setup": {
               "price": {/* ... */},
               "description": {/* ... */},
               "showZeroPrice": false
            },
            "recurring": {
               "price": {/* ... */},
               "description": {/* ... */},
               "showZeroPrice": false
            },
            "renewal": {/* ... */},
            "deposit": {/* ... */}
         },
         "refund": {/* ... */},
         "active": true
      }
   ],
   "resourceRates": [
      {
         "resourceId": "9baec2f7-2995-4527-8299-806687b148f1",
         "showInStore": true,
         "measurable": false,
         "showInCustomerPanel": true,
         "sortNumber": 999,
         "fees": {
            "setup": {/* ... */},
            "recurring": {/* ... */},
            "overuse": {/* ... */}
         },
         "publication": {/* ... */},
         "units": {/* ... */}
      },
      /* ... */
   ],
   "billingTerms": {/* ... */},
   "publication": {/* ... */},
   "category": {/* ... */},
   "serviceTemplate": {/* ... */},
   "serviceTerms": {/* ... */},
   "vendor": {/* ... */},
   "resources": {/* ... */}
}

← SKUManagement

ServicePlanCategory →

CloudBlue Commerce API

Previous topic

Next topic

ServicePlan¶

Schema¶

Properties¶

Relationship¶

Custom Operations¶

getPlanSwitches¶

getPlanPeriodSwitches¶

getPlanSwitchPolicies¶

Structures¶

ServicePlanPublication¶

ServicePlanSubscriptionPeriod¶

SubscriptionPeriod¶

ServicePlanSubscriptionPeriodFees¶

ServicePlanSubscriptionPeriodFeeSetup¶

Currency¶

ServicePlanSubscriptionPeriodFeeRecurring¶

ServicePlanSubscriptionPeriodFeeRenewal¶

ServicePlanSubscriptionPeriodFeeDeposit¶

ServicePlanSubscriptionPeriodRefund¶

ServicePlanSubscriptionPeriodResourceRate¶

ServicePlanResourceRateFees¶

ServicePlanResourceRateFeeSetup¶

ServicePlanResourceRateFeeRecurring¶

ServicePlanResourceRateFeeOveruse¶

FeeTier¶

DiscountTier¶

ServicePlanResourceRatePublication¶

ServicePlanResourceRatePublicationStore¶

ServicePlanResourceRate¶

ServicePlanResourceRateUnits¶

Display¶

ServicePlanBillingTerms¶

ServicePlanBillingPeriod¶

ServicePlanAutorenewal¶

ServicePlanSubscriptionPeriodSwitch¶

SwitchTarget¶

Fee¶

ResourceMapping¶

SwitchPolicies¶

ServicePlanSubscriptionPeriodSwitches¶

ServicePlanSwitch¶

MultiLangString¶

ServicePlanSwitchPolicy¶

Examples¶

Get all Service Plans¶

Get selected Service Plans¶

Get Service Plan Details¶

Schema ¶

Properties ¶

Relationship ¶

Custom Operations ¶

Structures ¶

Examples ¶