Query Compatible Plans

The Query Compatible Plans web service XML- or JSON-based information exchange systems that use the Internet for direct application-to-application interaction. These systems can include programs, objects, messages, or documents. is called to get Plans compatible for an existing subscription A billing entity that incurs a charge. Examples include a network attached device whose usage you want to measure and charge for, or a monthly software subscription to change to from within a selfcare application, such as an online portal for end users.

Eligibility criteria based on the supplied Sales Channel and Subscription is applied and only Plans valid for the supplied search criteria are returned.

The expand parameter for the request allows the client to return different levels of data. In this case, the extra levels of information that can be requested are the services and discounts that comprise the base package associated with the plan.

QueryCompatiblePlans Request

The mandatory QueryCompatiblePlans Request contains the following elements:

Field Name	Content Type	Description	Required?
ExternalReference	Container	Returned unmodified in the response. The client may use this identifier to correlate the request and the response.	Optional
SubscriptionNumber	Container	The ID that uniquely identifies the CMP Subscription.	Optional (but will always be supplied for certain customers depending on their requirements).
EligibilityRules	String	See the Rules definition in section . A parameter name of category is supplied with a value of 'Recommended'. 'Recommended' represents the active promotion being offered at this time via the online Sales Channel. By supplying this parameter, the web service returns the associated package in the response for each Plan where applicable	Optional (but will always be supplied for certain customers depending on their requirements).
Datasets	String 30	See Dataset.
Dataset	Container	Repeating field whereby the client can control the amount of data to return. It allows values to be specified to return the expanded definitions for the Base Package of each plan: i.e. Services and Discounts. Bundles (i.e. allowances, such as Data Allowances) are applied via Services, and will be returned as part of the Service definition when applicable.	Optional

EligibilityRules Request Container

The QueryCompatiblePlans 'EligibilityRules' Request Container has the following elements:

This Eligibility Rules definition is to be used for both Query Compatible Plans and Query Compatible Packages.

Element Name	Content Type	Description	Required?
Sales Channel	String30	The Sales Channel from where this request originates. Different Rules may be invoked based on the Sales Channel.	Mandatory
AsOfDate	Container	CMP allows three different patterns to supply when querying the dates for which the eligibility and compatibility rules should be returned. If no date information is supplied then a date of today is assumed. A Date parameter or On Bill Cycle may be supplied. See AsOfDate Request Container for further details.	Optional
Date	Date	The date that the compatibility rules should be applied to	Conditional
OnBillCycle	Boolean	When this is selected then the next bill cycle date is used to determine the list of plans/packages effective and compatible for that date.	Conditional
Parameters	Container	A facility to provide a list of name value pair specific to each implementation. See Parameters Request Container for further details.	Optional

AsOfDate Request Container

The 'AsOfDate' Request Container has the following elements:

Element Name	Content Type	Description	Required?
Date	Date	The date that the compatibility rules should be applied to.	Conditional
OnBillCycle	Boolean	When this is selected then the next bill cycle date is used to determine the list of plans/packages effective and compatible for that date.	Conditiional

Parameters Request Container

The 'Parameters' Request Container has the following elements:

Element Name	Content Type	Description	Required?
Name	String30	The valid values for this are determined by CMP configuration. For Query Compatible Plans: Category For Query Compatible Packages: Category
Value	String120	The valid values are determined by CMP configuration. For Query Compatible Plans the category supplied will be: Recommended Recommended is a "label" assigned to a set of packages that the customer wishes to apply to a particular Plan. These are returned in the Query Compatible Plans request and then must be supplied in a subsequent Change Tariff request as bolt-on packages to be created. For QueryCompatiblePackages the category supplied will be: Bolt-on Packages.

Element Name

Content Type

Description

Required?

Name

String30

The valid values for this are determined by CMP configuration.

For Query Compatible Plans: Category

For Query Compatible Packages: Category

Value

String120

The valid values are determined by CMP configuration.

For Query Compatible Plans the category supplied will be: Recommended

Recommended is a "label" assigned to a set of packages that the customer wishes to apply to a particular Plan. These are returned in the Query Compatible Plans request and then must be supplied in a subsequent Change Tariff request as bolt-on packages to be created.

For QueryCompatiblePackages the category supplied will be: Bolt-on Packages.

Sample QueryCompatiblePlans Request

Request Headers

Accept = application/xml if supplying the request as XML Exstensible Markup Language. A markup language used to describe data that allows users to define their information formats, especially in order to display documents on the Internet. or application/json to supply the request in JSON JavaScript Object Notation. JSON is a lightweight format for storing and transporting data, often used when data is sent from a server to a web page. format.

Content-Type = application/xml to return the data as XML or application/json to return the data in JSON format.

Request XML

<externalReference>MYACC-04405500-09900</externalReference>

<salesChannel>MYACCOUNT</salesChannel>

</eligibilityRules>

<dataset>RetainedPackages</dataset>

<dataset>Definitions</dataset>

</datasets>

</queryCompatiblePlans></queryCompatiblePlans>

QueryCompatiblePlans Response

The 'QueryCompatiblePlans' Response is the response to the 'QueryCompatiblePlans' Request. This contains the following fields:

Field Name	Content Type	Description	Required?
External Reference	String69	Returned unmodified in the response. The client may use this identifier to correlate the request and the response.	Optional
Plan	Container	See Plans Response Container for details.	Optional
Definitions	Container	If the Definition dataset is requested then the Definitions element is returned. See Definitions Response Container for details.	Optional

Field Name

Content Type

Description

Required?

External Reference

String69

Returned unmodified in the response. The client may use this identifier to correlate the request and the response.

Optional

Plan

Container

See Plans Response Container for details.

Optional

Definitions

Container

If the Definition dataset is requested then the Definitions element is returned.

See Definitions Response Container for details.

Optional

Plans Response Container

The 'Plans' Response Container has the following elements:

Field Name	Content Type	Description	Required?
Code	String6	The price plan code that uniquely identifies the plan.	Mandatory
TariffCode	String6	The tariff that is applicable to all subscriptions using this price plan.	Mandatory
PackageCode	String6	The default base package for this price plan.	Optional
Description	String30	The short description of the plan.	Mandatory
LongDescription	String120	The long description of the plan.	Optional
ToolTipText	String300	An extended description of the plan that may be used as a tool tip text.	Optional
TermsAndConditionsGroupCode	String6	This is the code for terms and conditions to be printed on the back of the invoice. The tariff for this price plan may have different terms and condition attached. The terms and conditions within this price plan, will override that within the tariff.	Optional
TermMonths	Integer	This is the length of time for which the subscription with this plan will be contracted. If a customer who signs onto this plan, is committing to a 12 month contract, then the term of contract would be 12. The tariff for this plan may also have a term of contract. The term of contract within this plan will override that within the tariff.	Optional
EffectiveDate	Date	This signifies the date from which the plan will become available.	Optional
ExpiryDate	Date	This is the date until which the plan will be available to apply to subscriptions.	Optional
ConnectionType	String4	Identifies the default connection workflow.	Mandatory
Corporate	Boolean	A true value indicates that the price plan can only be applied to Corporate Accounts.	Mandatory
Price	Currency (Decimal)	The full price of this plan. This will be derived from any chargeable services contained within both the base Package and any Recommended Packages for this plan. This represents the MRC for this Plan. Based on the Product Catalogue, this price will always be equal to the price of the Base package.	Mandatory
DiscountedPriceAtStart	Currency (Decimal)	The price as calculated above but with any Total Normal, Subscription Level discounts applied from the Base or Default Packages, or Sticky Promotion Packages compatible with the Plan in context. Based on the TalkTalk Product Catalogue currently active promotions will be reflected as Default Packages. There are many instances when the active promotion is a discount, in such circumstances, this value will calculate the MRC based on the base Package price but with the discount (as per default package) applied to it. Note, that discounts may have a delayed start before they are applied (see MonthsToStart field in the Discount Scheme Container Definition), those discounts will not be included in the DiscountedPriceAtStart value. Note: the discount will only be applied if the corresponding service for the discount (e.g. MRC) is contained within either the base or default packages, e.g. if the discount applied to usage this would not be reflected in this field.	Optional
PricePlanGroupCode	String 10	CMP will group Price Plans as part of the compatibility management.	Mandatory
Attributes	Container	Attributes are a configurable list of values that are used to describe the Plan. These can be configured as required by the customer. See Attribute Response Container page Query Compatible Plans for details.	Optional
Group	String6	The group allows attributes to be grouped together. For instance to distinguish between descriptive and rules attributes. Descriptive attributes are just for information purposes and rule attributes are ones that CMP will base logic on.	Mandatory
Name	String30	The attribute names are a configurable list of attributes that can be configured to meet a particular business or technical requirement. An example attribute name would be 'Band Type'.	Mandatory
SubscriptionPlanStatus	Container	This is returned when the request is in the context of a specific subscription. See SubscriptionPlanStatus Response Container page Query Compatible Plans for details.	Optional
DefaultPackages	Container	A container to hold the list of package codes of all the compatible default packages for the Plan. See DefaultPackages Response Container page Query Compatible Plans for details.	Optional
RetainedPackages	Container	A container to hold the list of package codes of the packages that will be retained should the subscription change to the plan. See RetainedPackages Response Container page Query Compatible Plans for details.	Optional

Attribute Response Container

The 'Attribute' Response Container has the following elements:

Field Name	Content Type	Description	Required?
Group	String6	The group allows attributes to be grouped together. For instance, to distinguish between descriptive and rules attributes. Descriptive attributes are just for information purposes and rule attributes are what CMP will base its logic on.	Mandatory
Name	String30	The attribute names are a configurable list of attributes that can be configured to meet a particular business or technical requirement. An example attribute name would be "Band Type".	Mandatory
Value	String120	This is the value of the attribute. An example of this (for the Attribute name example given above) would be "SIMO" or "2b".	Mandatory

Field Name

Content Type

Description

Required?

Group

String6

The group allows attributes to be grouped together. For instance, to distinguish between descriptive and rules attributes. Descriptive attributes are just for information purposes and rule attributes are what CMP will base its logic on.

Mandatory

Name

String30

The attribute names are a configurable list of attributes that can be configured to meet a particular business or technical requirement.

An example attribute name would be "Band Type".

Mandatory

Value

String120

This is the value of the attribute. An example of this (for the Attribute name example given above) would be "SIMO" or "2b".

Mandatory

SubscriptionPlanStatus Response Container

The 'SubscriptionPlanStatus' Response Container has the following elements:

Field Name	Content Type	Description	Required?
Status	Enumeration	This represents the current status of the plan in relation to the subscription: Possibles statuses are: Active Available 'Active' is the current plan that the subscription is on. 'Available 'indicates a plan that is available for the subscriber to move to.	Mandatory

Field Name

Content Type

Description

Required?

Status

Enumeration

This represents the current status of the plan in relation to the subscription:

Possibles statuses are:

Active
Available

'Active' is the current plan that the subscription is on.

'Available 'indicates a plan that is available for the subscriber to move to.

Mandatory

DefaultPackages Response Container

The 'DefaultPackages' Response Container has the following elements:

Field Name	Content Type	Description	Required?
PackageCode	String6	The identifier for the package.	Mandatory

RetainedPackages Response Container

The 'RetainedPackages' Response Container has the following elements:

Field Name	Content Type	Description	Required?
PackageCode	String6	The identifier for the package.	Mandatory

Definitions Response Container

The 'Definitions' Response Container has the following elements:

Field Name	Content Type	Description	Required?
Packages	Container	A container to hold the definition of all the different packages returned within the response, i.e. Base, Default and Retained packages. See Package Response Container page Query Compatible Plans for further details.	Mandatory

Field Name

Content Type

Description

Required?

Packages

Container

A container to hold the definition of all the different packages returned within the response, i.e. Base, Default and Retained packages.

See Package Response Container page Query Compatible Plans for further details.

Mandatory

Package Response Container

A package is composed of zero or more Services and zero or more discounts. CMP Converged Monetisation Platform. The MDS Global product that supports customer care and billing for digital service providers. has two types of package: a base package and a bolt-on An addition to a subscriber's main plan or product; also sometimes called an add-on. package. A particular subscription can have 0 or 1 base package and 0 or many bolt-on packages. For the customer In the context of the Cloud Monetisation Platform, an individual or organisation who has signed an agreement to take goods and services from a service provider. A customer receives a bill associated with one or more subscriptions, and can be a single end user or a large company with many subscriptions assigned to one agreement., each subscription will always have a base package.

A plan specify a base package which contains the inclusive bundles and the MRC as well as any inclusive discounts if required.

Bolt-on packages are used by the customer to apply boosts, discounts and promotions.

The 'Package' Response Container has the following elements:

Field Name	Content Type	Description	Required?
Code	String6	The package code that uniquely identifies the package in CMP.	Mandatory
PackageClassification	Enumeration	Possible Values: Base Package Bolton Package	Mandatory
Description	String30	The short description of the package	Mandatory
LongDescription	String120	The long Description of the package	Optional
ToolTipText	String300	An extended description that may be used as a tool tip text.	Optional
DurationInMonths	Integer2	The default number of months that the package will be valid for from the date it is applied to a subscription. In CMP setup, a default is configured against the package which may be overridden when the package is associated with a tariff. This allows the same Service or Discount to be specified in many different packages with different DurationInMonths value. Furthermore, at the point where there package is associated with the tariff, the default DurationInMonths value for individual services and discounts that comprise the package may be overridden.	Optional
EffectiveDate	Date	The effective date of a particular package can be different depending upon the context in which it is applied. CMP allows for the effective date to be overridden at several levels. When the package is initially created, there is a date upon which it may be associated with a Tariff. Then within the context of a particular selection group, the package can have different effective and expiry dates. When this field is returned in the context of Query Compatible Plans, then, the effective date can be different for different instances of this package code and only one definition is being returned, therefore, the effective date will be that associated with the original configuration of the package before it was associated with any tariff or selection group. When this field is returned in the context of a Query Compatible Packages, the effective date will be the value for when the package was associated with the tariff of the plan in context.	Mandatory
ExpiryDate	Date	The date from which this package can no longer be added to a subscription. This contains similar logic to the Effective Date above. Packages already added to subscriptions will not be affected by the expiry date.	Optional
Price	Decimal	The price of the package. This is derived by summing up the price of the services on the package. It does not apply any Discount.	Optional
DiscountedPriceAtStart	Decimal	This field will not be returned in the context of a Query Compatible Plans response. The discounted price of the package upon application. If there are no discounts to be applied upon application of package, this field will not be included on the response. Discounts may have a delayed start before they are applied (see MonthsToStart field in the Discount Scheme Container Definition). Those discounts will not be included in the DiscountedPriceAtStart value. Also, the DiscountPriceAtStart can only be applied if the services to which it applies exist within the same Package. E.g. if the Base Package has a Service, MEDMRC, which represents an MRC for 20.00, and the Subscription gets a Discount Promotion (that is, a separate bolt-on Package) for 50% off MEDMRC. Then the DiscountPriceAtStart for this will not appear in any context. The DiscountPriceAtStart will occur in scenarios where the user has a Plan or Bolt-on Package which has a discounted price for the first X months.	Optional
PrimaryPackageGroupCode	String10	CMP will group packages as part of the compatibility management.	Optional
Attributes	Container	Attributes are a configurable list of values that are used to describe the package See the Attribute Response Container page Query Compatible Plans for details.	Optional
SubscriptionPackageStatus	Container	This is never returned in a Query Compatible Plans Response. It only applies to a Query Compatible Packages response. This is returned for bolt-on packages when the request is in the context of a specific subscription. See the SubscriptionPlanStatus Response Container further details.	Optional
Services	Container	Contains one or more Service containers. See Service Response Container for further details.	Optional
DiscountSchemes	Container	Contains one or more DiscountScheme containers. See DiscountScheme Response Container for further details.	Optional