BSSSubscription¶

The platform uses this APS type to create APS resources representing subscriptions to service plans in BSS. External systems use the API exposed by this APS to operate the existing subscriptions.

In this document:

Schema
Properties
Relationship
Custom Operations
Structures
Examples

Schema ¶

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

{
  "name": "BSSSubscription",
  "id": "http://www.odin.com/billing/Subscription/1.0",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0",
    "http://aps-standard.org/types/core/subscription/migratable/1.0"
  ],
  "relations": {
    "account": {
      "type": "http://parallels.com/aps/types/pa/account/1.2",
      "backrel": false
    },
    "bssAccountInfo": {
      "type": "http://parallels.com/pa/bss-account-info/1.0",
      "backrel": false
    },
    "vendor": {
      "type": "http://parallels.com/aps/types/pa/account/1.2",
      "backrel": false
    },
    "servicePlan": {
      "type": "http://www.odin.com/billing/ServicePlan/1.1",
      "backrel": false
    },
    "parentSubscription": {
      "type": "http://www.odin.com/billing/Subscription/1.0"
    },
    "childSubscriptions": {
      "type": "http://www.odin.com/billing/Subscription/1.0",
      "collection": true
    },
    "paSubscription": {
      "type": "http://parallels.com/aps/types/pa/subscription/1.0",
      "backrel": false
    }
  },
  "properties": {
    "subscriptionId": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "subscriptionPeriod": {
      "type": "SubscriptionPeriod"
    },
    "trial": {
      "type": "boolean"
    },
    "status": {
      "type": "string",
      "enum": [
        "NEW",
        "ACTIVE",
        "ADMINISTRATIVE_HOLD",
        "CREDIT_HOLD",
        "FULL_HOLD",
        "GRACE",
        "EXPIRED",
        "TERMINATED"
      ]
    },
    "serviceStatus": {
      "type": "string",
      "enum": [
        "NOT_EXIST",
        "CREATING",
        "STARTING",
        "ACTIVE",
        "CHANGING_PLAN",
        "STOPPING",
        "STOPPED",
        "DESTROYING",
        "DESTROYED"
      ]
    },
    "serviceGate": {
      "type": "string"
    },
    "startDate": {
      "type": "string",
      "format": "date"
    },
    "lastBillDate": {
      "type": "string",
      "format": "date"
    },
    "nextBillDate": {
      "type": "string",
      "format": "date"
    },
    "autoRenewDate": {
      "type": "string",
      "format": "date"
    },
    "expirationDate": {
      "type": "string",
      "format": "date"
    },
    "shutdownDate": {
      "type": "string",
      "format": "date"
    },
    "terminationDate": {
      "type": "string",
      "format": "date"
    },
    "autoRenewEnabled": {
      "type": "boolean"
    },
    "billingTerms": {
      "type": "BillingTerms"
    },
    "attributes": {
      "type": "array",
      "items": {
        "type": "Attribute"
      }
    }
  },
  "operations": {
    "getResources": {
      "path": "/resources",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "SubscriptionResource"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "getServiceParameters": {
      "path": "/serviceParameters",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "ServiceParameter"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "getPrices": {
      "path": "/prices",
      "verb": "GET",
      "response": {
        "type": "SubscriptionPricing"
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "updatePrices": {
      "path": "/prices",
      "verb": "PUT",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      },
      "parameters": {
        "prices": {
          "kind": "body",
          "type": "SubscriptionPricing)"
        }
      }
    },
    "getCosts": {
      "path": "/costs",
      "verb": "GET",
      "response": {
        "type": "SubscriptionCosts"
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "setPaymentMethods": {
      "path": "/paymentMethods",
      "verb": "PUT",
      "errorResponse": {
        "type": "object"
      }
    },
    "getPaymentMethods": {
      "path": "/paymentMethods",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "PaymentMethod"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "autoRenew": {
      "path": "/autoRenew",
      "verb": "PUT",
      "response": {
        "type": "BSSSubscription"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "autoRenew": {
          "kind": "body",
          "type": "AutoRenewalEnable)"
        }
      }
    },
    "putOnAdministrativeHold": {
      "path": "/putOnHold",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      },
      "parameters": {
        "parameters": {
          "kind": "body",
          "type": "PutOnHoldParameters)"
        }
      }
    },
    "putOnCreditHold": {
      "path": "/putOnCreditHold",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      },
      "parameters": {
        "parameters": {
          "kind": "body",
          "type": "PutOnHoldParameters)"
        }
      }
    },
    "releaseFromAdministrativeHold": {
      "path": "/releaseFromHold",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      },
      "parameters": {
        "parameters": {
          "kind": "body",
          "type": "ReleaseFromHoldParameters)"
        }
      }
    },
    "releaseFromCreditHold": {
      "path": "/releaseFromCreditHold",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      },
      "parameters": {
        "parameters": {
          "kind": "body",
          "type": "ReleaseFromHoldParameters)",
          "required": true
        }
      }
    }
  },
  "structures": {
    "SubscriptionPeriod": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "enum": [
            "DAYS",
            "MONTHS",
            "YEARS"
          ]
        },
        "duration": {
          "type": "integer"
        }
      }
    },
    "BillingTerms": {
      "type": "object",
      "properties": {
        "billingModel": {
          "type": "string",
          "enum": [
            "CHARGE_BEFORE_BILLING_PERIOD",
            "CHARGE_AFTER_BILLING_PERIOD",
            "CHARGE_BEFORE_SUBSCRIPTION_PERIOD",
            "CHARGE_USING_EXTERNAL_RATING"
          ]
        },
        "billingPeriod": {
          "type": "BillingPeriod"
        },
        "freezePrices": {
          "type": "boolean"
        },
        "autoRenewal": {
          "type": "AutoRenewal"
        },
        "fullRefundPeriod": {
          "type": "integer"
        }
      }
    },
    "BillingPeriod": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "enum": [
            "STATEMENT_DAY",
            "MONTHS",
            "YEARS"
          ]
        },
        "duration": {
          "type": "integer"
        }
      }
    },
    "AutoRenewal": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "DISABLED",
            "BEFORE_EXPIRATION_DATE",
            "ON_LAST_STATEMENT_DATE"
          ]
        },
        "days": {
          "type": "integer"
        }
      }
    },
    "Attribute": {
      "type": "object",
      "properties": {
        "attributeId": {
          "type": "string",
          "required": true
        },
        "value": {
          "type": "string"
        }
      }
    },
    "IncludedResource": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "description": "BSSResource APS ID",
          "required": true
        },
        "internalResourceId": {
          "type": "integer",
          "description": "Internal Resource ID",
          "required": true
        },
        "name": {
          "type": "MLString"
        },
        "unitOfMeasureId": {
          "type": "string"
        },
        "unitOfMeasure": {
          "type": "MLString"
        },
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        },
        "multiplier": {
          "type": "integer"
        },
        "usage": {
          "type": "number"
        }
      }
    },
    "SubscriptionResource": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "description": "BSSResource APS ID",
          "required": true
        },
        "internalResourceId": {
          "type": "integer",
          "description": "Internal Resource ID",
          "required": true
        },
        "status": {
          "type": "string",
          "enum": [
            "PURCHASED",
            "PROVISIONING",
            "INSTALLED",
            "FAILED",
            "ORDERED",
            "NOT_PRESENT",
            "REMOVE",
            "DISABLED",
            "OPTIONAL"
          ]
        },
        "name": {
          "type": "MLString"
        },
        "unitOfMeasureId": {
          "type": "string"
        },
        "unitOfMeasure": {
          "type": "MLString"
        },
        "measurable": {
          "type": "boolean"
        },
        "showInCustomerPanel": {
          "type": "boolean"
        },
        "allowToModifyInTrial": {
          "type": "boolean"
        },
        "included": {
          "type": "number"
        },
        "additional": {
          "type": "number"
        },
        "ordered": {
          "type": "number"
        },
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        },
        "usage": {
          "type": "number"
        },
        "includedResources": {
          "type": "array",
          "items": {
            "type": "IncludedResource"
          }
        }
      }
    },
    "ServiceParameter": {
      "type": "object",
      "properties": {
        "parameterId": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      }
    },
    "Period": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "enum": [
            "MONTHS",
            "YEARS"
          ]
        },
        "duration": {
          "type": "integer"
        }
      }
    },
    "Prices": {
      "type": "object",
      "properties": {
        "promotion": {
          "type": "PromotionInfo"
        },
        "nonRefundableAmount": {
          "type": "Currency"
        },
        "subscriptionFees": {
          "type": "array",
          "items": {
            "type": "SubscriptionFee"
          }
        },
        "resourceFees": {
          "type": "array",
          "items": {
            "type": "ResourceRateFee"
          }
        }
      }
    },
    "PromotionInfo": {
      "type": "object",
      "properties": {
        "promotionId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "availableUntil": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "Currency": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string"
        },
        "code": {
          "type": "String)"
        }
      }
    },
    "SubscriptionFee": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "SETUP",
            "RECURRING",
            "RENEWAL",
            "TRANSFER"
          ]
        },
        "price": {
          "type": "Currency)"
        },
        "discount": {
          "type": "Discount"
        }
      }
    },
    "Discount": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "PERCENT",
            "FIXED"
          ]
        },
        "value": {
          "type": "number"
        },
        "amount": {
          "type": "number"
        }
      }
    },
    "ResourceRateFee": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "String)"
        },
        "type": {
          "type": "string",
          "enum": [
            "SETUP",
            "RECURRING",
            "OVERUSE"
          ]
        },
        "priceModel": {
          "type": "string",
          "enum": [
            "FLAT",
            "TIERED",
            "VOLUME"
          ]
        },
        "price": {
          "type": "Currency)"
        },
        "tiers": {
          "type": "array",
          "items": {
            "type": "FeeTier"
          }
        },
        "showZeroPrice": {
          "type": "boolean"
        },
        "chargePerUnit": {
          "type": "boolean"
        },
        "chargeForUpgrade": {
          "type": "boolean"
        },
        "discount": {
          "type": "Discount"
        }
      }
    },
    "FeeTier": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "lowerLimit": {
          "type": "number"
        },
        "discount": {
          "type": "Discount"
        }
      }
    },
    "SubscriptionPricing": {
      "type": "object",
      "properties": {
        "period": {
          "type": "Period"
        },
        "costs": {
          "type": "Prices"
        },
        "prices": {
          "type": "Prices"
        }
      }
    },
    "Costs": {
      "type": "object",
      "properties": {
        "totalCost": {
          "type": "Currency"
        },
        "subscriptionCost": {
          "type": "SimpleCost"
        },
        "resourcesCosts": {
          "type": "array",
          "items": {
            "type": "ResourceRateCost"
          }
        }
      }
    },
    "SimpleCost": {
      "type": "object",
      "properties": {
        "cost": {
          "type": "Currency"
        },
        "discount": {
          "type": "Discount"
        }
      }
    },
    "ResourceRateCost": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string"
        },
        "name": {
          "type": "MLString"
        },
        "quantity": {
          "type": "number"
        },
        "tiers": {
          "type": "array",
          "items": {
            "type": "TierCost"
          }
        }
      }
    },
    "TierCost": {
      "type": "object",
      "properties": {
        "lowerLimit": {
          "type": "number"
        },
        "quantity": {
          "type": "number"
        }
      }
    },
    "SubscriptionCosts": {
      "type": "object",
      "properties": {
        "period": {
          "type": "Period"
        },
        "costs": {
          "type": "Costs"
        },
        "prices": {
          "type": "Costs"
        }
      }
    },
    "PaymentMethod": {
      "type": "object",
      "properties": {
        "paymentMethodId": {
          "type": "integer"
        }
      }
    }
  }
}

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/bss-subscriptions?<RQL-filter>

Properties ¶

NAME	TYPE	ATTRIBUTES	DESCRIPTION
subscriptionId	Integer	Not Required	The platform internal subscription ID.
name	String	Not Required	The subscription name.
subscriptionPeriod	SubscriptionPeriod	Not Required	Subscription period
trial	Boolean	Not Required	If true, the subscription period is a trial period.
status	Enum	Not Required	Identifies the subscription status (when estimating a service status, refer to the `ServiceStatus` property). Identifies the subscription status that can be one of the following (when estimating a subscription status, also refer to the `ServiceStatus` property): `NEW`: this is a new subscription in the process of provisioning. `ACTIVE`: the subscription functions normally providing the services to the subscriber. `ADMINISTRATIVE_HOLD`: the subscription is put on hold by the subscriber’s sales vendor. The subscription services are stopped. `CREDIT_HOLD`: the subscription is put on hold due to subscriber’s debts. The subscription services are stopped. `FULL_HOLD`: this status is related to the subscriber’s status and occurs in one of the following two cases. One case is when the subscriber is put on both `ADMINISTRATIVE_HOLD` and `CREDIT_HOLD`. Another case is when the subscriber is put on one of the hold types and the subscription is put on the other hold type. `GRACE`: the subscription is expired and not renewed yet. The services are still gracefully active. `EXPIRED`: the subscription period is expired and it passed the grace period. The related data is alive, although the services are stopped (see the `ServiceStatus` property). `TERMINATED`: the subscription is terminated and the services are stopped.
serviceStatus	Enum	Not Required	The status of the services provided by the subscription. Identifies the status of the services provided by the subscription. It can be one of the following: `NOT_EXIST`: the services are not provisioned yet. `CREATING`: the service provisioning is in progress. `STARTING`: the service provisioning is started. `ACTIVE`: the service functions normally. `CHANGING_PLAN`: the services along with the subscription are transferring to another service plan. `STOPPING`: the services are in the process of stopping. `STOPPED`: the services are unavailable.
serviceGate	String	Not Required	The gateway to the system providing the subscription services.
startDate	String	Not Required	The starting date of the subscription.
lastBillDate	String	Not Required	The date when the subscription was billed last time.
nextBillDate	String	Not Required	The date when the subscription is due to be billed next.
autoRenewDate	String	Not Required	If auto-renewal is enabled, specifies the planned date of the automatic subscription period renewal.
expirationDate	String	Not Required	The date when the subscription expires.
shutdownDate	String	Not Required	The date when the expired subscription is due to be stopped.
terminationDate	String	Not Required	The date when the expired subscription is due to be destroyed.
autoRenewEnabled	Boolean	Not Required	If true, the subscription is due to renew automatically. This is related to the `autoRenewDate` property.
billingTerms	BillingTerms	Not Required	The structure inherited from the service plan that defines a policy of charging the subscriber for the service usage.
attributes	Array of Attribute	Not Required	A set of named custom attributes.

Relationship ¶

NAME	TYPE	REQUIRED	DESCRIPTION
account	PAAccount	No	The subscription owner - subscriber.
bssAccountInfo	BssAccountInformation	No	The BSS data of the subscription owner.
vendor	PAAccount	No	The service plan sales vendor: the provider or a reseller.
servicePlan	ServicePlan	No	The service plan that the subscription is based on.
parentSubscription	BSSSubscription	No	The parent subscription, that is the linked subscription that the current subscription depends on.
childSubscriptions	Collection of BSSSubscription	No	The linked child subscriptions that depend on the current subscription.
paSubscription	PASubscription	No	The subscription counterpart in OSS responsible for service provisioning.

OPERATION	VERB	PATH	RETURNS	Description
getResources	GET	/resources	Collection of SubscriptionResource	Get resources of the specified subscription.
getServiceParameters	GET	/serviceParameters	Collection of ServiceParameter	Get the service provisioning parameters.
getPrices	GET	/prices	SubscriptionPricing structure	The operation is used to get the price structure for the subscription including the price for its resources. The returned data contains the cost details for the sales vendor and the price details for the specified customer.
updatePrices	PUT	/prices	Void.	This operation updates the price for the specified customer and the cost for the sales vendor.
getCosts	GET	/costs	SubscriptionCosts structure	This operation enables a reseller to get the cost and price details on the subscription recurring fees.
setPaymentMethods	PUT	/paymentMethods		This operation changes payment methods for the specified subscription. If collection is empty payment methods will be deleted from the subscription
getPaymentMethods	GET	/paymentMethods	Collection of payment methods for this subscription	This operation returns collection of payment methods for the subscription
autoRenew	PUT	/autoRenew	Updated BSSSubscription structure	This operation enables or disables the subscription auto-renewal process.
putOnAdministrativeHold	POST	/putOnHold	Void.	This operation puts the subscription on the administrative hold. It stops the subscription services.
putOnCreditHold	POST	/putOnCreditHold	Void.	This operation puts the subscription on the credit hold. It stops the subscription services.
releaseFromAdministrativeHold	POST	/releaseFromHold	Void.	This operation releases the subscription from the administrative hold.
releaseFromCreditHold	POST	/releaseFromCreditHold	Void.	This operation releases the subscription from the credit hold.

The operation is used to get the price structure for the subscription including the price for its resources. The returned data contains the cost details for the sales vendor and the price details for the specified customer.

Returns

SubscriptionPricing structure

updatePrices¶

HTTP Request

PUT /aps/2/resources/{aps-id}/prices

Description

This operation updates the price for the specified customer and the cost for the sales vendor.

Parameters

PARAMETER	TYPE	DESCRIPTION
prices	SubscriptionPricing)	SubscriptionPricing structure

Returns

Void.

getCosts¶

HTTP Request

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

Description

This operation enables a reseller to get the cost and price details on the subscription recurring fees.

Returns

SubscriptionCosts structure

setPaymentMethods¶

HTTP Request

PUT /aps/2/resources/{aps-id}/paymentMethods

Description

This operation changes payment methods for the specified subscription. If collection is empty payment methods will be deleted from the subscription

Returns

getPaymentMethods¶

HTTP Request

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

Description

This operation returns collection of payment methods for the subscription

Returns

Collection of payment methods for this subscription

autoRenew¶

HTTP Request

PUT /aps/2/resources/{aps-id}/autoRenew

Description

This operation enables or disables the subscription auto-renewal process.

Parameters

PARAMETER	TYPE	DESCRIPTION
autoRenew	AutoRenewalEnable)	AutoRenewalEnable structure

Returns

Updated BSSSubscription structure

putOnAdministrativeHold¶

HTTP Request

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

Description

This operation puts the subscription on the administrative hold. It stops the subscription services.

Parameters

PARAMETER	TYPE	DESCRIPTION
parameters	PutOnHoldParameters)	PutOnHoldParameters structure

Returns

Void.

putOnCreditHold¶

HTTP Request

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

Description

This operation puts the subscription on the credit hold. It stops the subscription services.

Parameters

PARAMETER	TYPE	DESCRIPTION
parameters	PutOnHoldParameters)	PutOnHoldParameters structure

Returns

Void.

releaseFromAdministrativeHold¶

HTTP Request

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

Description

This operation releases the subscription from the administrative hold.

Parameters

PARAMETER	TYPE	DESCRIPTION
parameters	ReleaseFromHoldParameters)	ReleaseFromHoldParameters structure

Returns

Void.

releaseFromCreditHold¶

HTTP Request

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

Description

This operation releases the subscription from the credit hold.

Parameters

PARAMETER	TYPE	DESCRIPTION
parameters	ReleaseFromHoldParameters)	ReleaseFromHoldParameters structure

Returns

Void.

Structures ¶

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.

BillingTerms¶

Defines the subscription charge policy.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
billingModel	Enum	Not Required	Defines the billing model for charging the subscriber.
billingPeriod	BillingPeriod	Not Required	Defines the billing period of subscription.
freezePrices	Boolean	Not Required	If true, the price for subscription renewal will be defined by the subscription configuration, otherwise by the service plan configuration.
autoRenewal	AutoRenewal	Not Required	Defines the subscription auto-renewal policy.
fullRefundPeriod	Integer	Not Required	The length of the period in the number of days during which the subscription can be fully refunded.

BillingPeriod¶

Defines the subscription billing period.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
unit	Enum	Not Required		Defines the billing period type for the subscription, that is either one month or one year, and in the former case whether it is bound to the statement day. Service plan billing period unit type.
duration	Integer	Not Required		Depending on the billing period type, defines the billing period length as a number of months or years.

AutoRenewal¶

The structure that defines the subscription auto-renewal policy.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
type	Enum	Not Required		Defines the subscription auto-renewal policy.
days	Integer	Not Required		If the subscription must be renewed automatically before its expiration date, this property defines the day when the renewal is due to start. This is defined by counting the specified number of days backward from the expiration date.

Attribute¶

The structure that defines the custom attribute.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
attributeId	String	Required		The attribute ID.
value	String	Not Required		The attribute value.

IncludedResource¶

The structure of a resource inside a composite resource.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
resourceId	String	Required	APS ID of corresponding BSSResource.
internalResourceId	Integer	Required	The platform internal resource ID.
name	MLString	Not Required	The resource name in the multilingual format.
unitOfMeasureId	String	Not Required	The unit of measurement ID.
unitOfMeasure	MLString	Not Required	The unit of measure in the multilingual format.
min	Number	Not Required	The minimal amount of the resource in the subscription. The subscriber cannot downgrade the resource limit below this value.
max	Number	Not Required	The maximum amount of the resource in the subscription. The resource limit or usage in the subscription cannot exceed the specified value. If the property is not specified, the maximum is unlimited.
multiplier	Integer	Not Required	Specifies the amount of a regular resource to include to the composite resource.
usage	Number	Not Required	The current resource usage.

SubscriptionResource¶

Subscription resource information

NAME	TYPE	ATTRIBUTES	DESCRIPTION
resourceId	String	Required	APS ID of corresponding BSSResource.
internalResourceId	Integer	Required	The platform internal resource ID.
status	Enum	Not Required	The resource status. Subscription resource status enumerator
name	MLString	Not Required	The resource name in the multilingual format.
unitOfMeasureId	String	Not Required	The unit of measurement ID.
unitOfMeasure	MLString	Not Required	The unit of measure in the multilingual format.
measurable	Boolean	Not Required	The flag indicating that resource is measurable.
showInCustomerPanel	Boolean	Not Required	The flag to show/hide resource in customer panel.
allowToModifyInTrial	Boolean	Not Required	The flag to enable/disable resource modification in trial period.
included	Number	Not Required	The included resource amount.
additional	Number	Not Required	The additionally purchased resource amount.
ordered	Number	Not Required	Ordered, but not provisioned resource amount.
min	Number	Not Required	The minimal amount of the resource in the subscription. The subscriber cannot downgrade the resource limit below this value.
max	Number	Not Required	The maximum amount of the resource in the subscription. The resource limit or usage in the subscription cannot exceed the specified value. If the property is not specified, the maximum is unlimited.
usage	Number	Not Required	The current resource usage.
includedResources	Array of IncludedResource	Not Required	The set of resources inside a composite resource.

ServiceParameter¶

The provisioning parameter structure.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
parameterId	String	Not Required		The parameter ID
value	String	Not Required		The parameter value.

Period¶

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
unit	Enum	Not Required		Period unit. Available values are “MONTHS” and “YEARS”.
duration	Integer	Not Required		Period duration.

Prices¶

The subscription price structure.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
promotion	PromotionInfo	Not Required	The promotion applied to the subscription.
nonRefundableAmount	Currency	Not Required	The price below this value is not refunded when the subscriber cancels the subscription.
subscriptionFees	Array of SubscriptionFee	Not Required	Subscription fees.
resourceFees	Array of ResourceRateFee	Not Required	Resources fees.

PromotionInfo¶

The structure of the promotion the subscription is bound to.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
promotionId	String	Not Required	The promo ID.
name	String	Not Required	The promotion name.
availableUntil	String	Not Required	The date until which the promotion is still available.

Currency¶

Basic currency structure.

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

SubscriptionFee¶

The subscription fee structure.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
type	Enum	Not Required	The subscription fee type. The fee type is one of the following: `SETUP`: one time fee for the whole subscription life-cycle. `RECURRING`: periodical fee that the subscriber is charged once per billing period. `RENEWAL`: periodical fee that the subscriber is charged for the subscription period renewal. `TRANSFER`: one time fee for transfering the domain registration subscription to another domain registrar.
price	Currency)	Not Required	The fee value.
discount	Discount	Not Required	The exclusive discount information. Read only.

Discount¶

NAME	TYPE	ATTRIBUTES	DESCRIPTION
type	Enum	Not Required	Discount type. Possible values are “PERCENT”, “FIXED”.
value	Number	Not Required	Discount value.
amount	Number	Not Required	Discount amount.

ResourceRateFee¶

The fee structure for a SubscriptionResource.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
resourceId	String)	Not Required	The APS ID of the BSSResource.
type	Enum	Not Required	The type of the resource fee.
priceModel	Enum	Not Required	The price model of the resource.
price	Currency)	Not Required	The resource fee when the flat price model is used.
tiers	Array of FeeTier	Not Required	The resource fee tiers when the tiered price model is used.
showZeroPrice	Boolean	Not Required	If true, the marketplace shows the resource price even when it is zero.
chargePerUnit	Boolean	Not Required	If true, the resource fee is assigned per resource unit, otherwise it is assigned to the specified amount of the resource.
chargeForUpgrade	Boolean	Not Required	If true, the subscriber is charged for the resource setup fee when upgrading a resource (in accordance with the resource setup fee configuration); otherwise the invoice does not contain the setup fee for the resource upgrade.
discount	Discount	Not Required	The exclusive discount information. Read only.

FeeTier¶

This structure contain information about resource tier limit

NAME	TYPE	ATTRIBUTES
price	Currency	Not Required
lowerLimit	Number	Not Required
discount	Discount	Not Required

SubscriptionPricing¶

The subscription price structure.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
period	Period	Not Required	The effective period for which the prices are calculated.
costs	Prices	Not Required	When requested by a sales vendor, this is the subscription prices and details for the sales vendor. When requeset by a customer, this is the subscription prices and details for the customer.
prices	Prices	Not Required	When requested by a sales vendor, this is the subscription price and details for the subscriber. Customers cannot request the prices.

Costs¶

The subscription total cost and cost details.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
totalCost	Currency	Not Required	The subscription total cost.
subscriptionCost	SimpleCost	Not Required	The subscription total cost excluding the cost for additional resources amount.
resourcesCosts	Array of ResourceRateCost	Not Required	The total cost for all additional resources amounts.

SimpleCost¶

The structure that

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
cost	Currency	Not Required		The cost of a subscription item.
discount	Discount	Not Required		The discount applied to the subscription item.

ResourceRateCost¶

The total cost of a resource rate.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
resourceId	String	Not Required	The APS ID of the BSSResource.
name	MLString	Not Required	The resource name in the multilingual format.
quantity	Number	Not Required	The amount of additional resources.
tiers	Array of TierCost	Not Required	The set of resource tiers.

TierCost¶

The tier cost per resource unit.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
lowerLimit	Number	Not Required		The lower limit of a resource tier.
quantity	Number	Not Required		The amount of the resource in the specified fee tier.

SubscriptionCosts¶

The subscription costs.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
period	Period	Not Required	The effective period for which the costs are calculated.
costs	Costs	Not Required	The subscription cost total and details estimated for the requester.
prices	Costs	Not Required	When requested by a sales vendor, this is the subscription cost total and details estimated for the specified customer. Customers cannot request the prices.

PaymentMethod¶

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
paymentMethodId	Integer	Not Required

Examples ¶

Below are examples of using the BSSSubscription operations in some common cases.

In this section:

Select Subscriptions by Account
Get Subscription Details
Get Resource Usage
Manage Payment Methods

Select Subscriptions by Account ¶

To list the subscriptions of a certain customer, filter the subscriptions by the account.aps.id property as in the following example:

GET /aps/2/collections/bss-subscriptions?eq(account.aps.id,78560b5e-a762-4d52-b300-00543113e1d4)

Use the select RQL function to restrict the list of the returned data as in the following example that requests a list of all subscriptions along with the linked accounts and shows only the subscription name and the owner’s companyName:

Request:

GET /aps/2/collections/bss-subscriptions?like(name,*Demo*),select(name,account.companyName)

The response shows the requested parameters (the aps section is not filtered out by RQL):

HTTP/1.1 200 OK

[
  {
    "aps": {
      "modified": "2019-03-12T18:00:59Z",
      "id": "456808a0-b5a6-4092-ab67-b77e33743a07",
      "type": "http://www.odin.com/billing/Subscription/1.0",
      "status": "aps:ready",
      "revision": 17
    },
    "name": "VPS Demo Services",
    "account": {
      "aps": {
        "modified": "2019-03-12T07:28:20Z",
        "id": "78560b5e-a762-4d52-b300-00543113e1d4",
        "type": "http://parallels.com/aps/types/pa/account/1.2",
        "status": "aps:ready",
        "revision": 4
      },
      "companyName": "John Smith"
    }
  }
]

Get Subscription Details ¶

To get more details about a subscription than those returned in the list of subscriptions, request those details by the following request that specifies the APS ID of the requested subscription:

GET /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07

The response shows detailed data about the subscription:

HTTP/1.1 200 OK

{
  "aps": {
    "schema": "/aps/2/types/156",
    "package": {
      "id": "92ccf5e8-fc07-4e7f-8875-5c19c8545870",
      "href": "/aps/2/packages/92ccf5e8-fc07-4e7f-8875-5c19c8545870"
    },
    "modified": "2019-03-12T13:19:54Z",
    "id": "456808a0-b5a6-4092-ab67-b77e33743a07",
    "type": "http://www.odin.com/billing/Subscription/1.0",
    "status": "aps:ready",
    "revision": 11
  },
  "subscriptionPeriod": {
    "duration": 3,
    "unit": "MONTHS"
  },
  "shutdownDate": "2019-03-12",
  "name": "VPS Demo Services",
  "billingTerms": {
    "billingPeriod": {
      "duration": 1,
      "unit": "MONTHS"
    },
    "freezePrices": false,
    "billingModel": "CHARGE_BEFORE_BILLING_PERIOD",
    "autoRenewal": {
      "type": "DISABLED"
    }
  },
  "vendor": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/2df1f8f0-39df-4f57-b810-e46e600eddab",
      "id": "2df1f8f0-39df-4f57-b810-e46e600eddab"
    }
  },
  "subscriptionId": 1000001,
  "serviceGate": "PEMGATE",
  "bssAccountInfo": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/66a19490-e738-4455-85b6-658b9780e764",
      "id": "66a19490-e738-4455-85b6-658b9780e764"
    }
  },
  "trial": false,
  "startDate": "2019-03-12",
  "serviceStatus": "STOPPED",
  "status": "TERMINATED",
  "terminationDate": "2019-04-11",
  "autoRenewEnabled": false,
  "paSubscription": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/4b9d0e6f-ba57-4c3d-9d28-e52b138787fb",
      "id": "4b9d0e6f-ba57-4c3d-9d28-e52b138787fb"
    }
  },
  "servicePlan": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/f282224a-68d0-413e-ab2b-5d836a1abd5d",
      "id": "f282224a-68d0-413e-ab2b-5d836a1abd5d"
    }
  },
  "account": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/78560b5e-a762-4d52-b300-00543113e1d4",
      "id": "78560b5e-a762-4d52-b300-00543113e1d4"
    }
  },
  "nextBillDate": "2019-03-12",
  "lastBillDate": "2019-03-12",
  "childSubscriptions": {
    "aps": {
      "link": "collection",
      "href": "/aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/childSubscriptions"
    }
  },
  "expirationDate": "2019-06-12"
}

Get Resource Usage ¶

The APS type defines the resources operation that lists the subscribed resources sold through the respective service plan with the limitation and actual usage for every resource. To get this data from a subscription, send a REST request similar to the following:

Request:

GET /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/resources

The response shows the list of resources with the limit, usage, and unit properties in each of them as in this example:

HTTP/1.1 200 OK

[
  {
    "resourceId": "bc88fcde-4235-49a9-8ef6-7fa886b48ef3",
    "internalResourceId": 1000060,
    "status": "INSTALLED",
    "name": {
      "en_US": "VPS Demo Services - Virtual Server"
    },
    "unitOfMeasureId": "unit",
    "unitOfMeasure": {
      "en_US": "unit"
    },
    "measurable": false,
    "showInCustomerPanel": true,
    "allowToModifyInTrial": false,
    "included": "1.0",
    "additional": "4.0",
    "ordered": "0.0",
    "min": "1.0",
    "usage": "0.0"
  }
]

Manage Payment Methods ¶

A subscription can have an attached payment method that is used by default in all payment operations related with this subscription.

Note

1. The attached payment method is used when a payment method is not specified explicitly in an order related to this subscription.

Currently, you can attach only one payment method to a subscription.

To attach an existing payment method to a subscription, call the setPaymentMethods operation as in the following example:

PUT /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/paymentMethods

[
    {
        "paymentMethodId": 11
    }
]

If successful, the response is “204 No Content”.

To determine if a subscription has an attached payment method, call the getPaymentMethods operation as in the following example:

GET /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/paymentMethods

If successful, the response is as in the following example:

HTTP/1.1 200 OK

[
    {
        "paymentMethodId": 11
    }
]

To detach a payment method from a subscription, call the setPaymentMethods operation with the empty body as in the following example:

PUT /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/paymentMethods

[ ]

For other operations with payment methods, refer to PaymentMethodManagement.

← BSSResource

BssAccountInformation →

CloudBlue Commerce API (DRAFT)

Table Of Contents

Previous topic

Next topic

BSSSubscription¶

getResources¶

getServiceParameters¶

getPrices¶

updatePrices¶

getCosts¶

setPaymentMethods¶

getPaymentMethods¶

autoRenew¶

putOnAdministrativeHold¶

putOnCreditHold¶

releaseFromAdministrativeHold¶

releaseFromCreditHold¶

SubscriptionPeriod¶

BillingTerms¶

BillingPeriod¶

AutoRenewal¶

Attribute¶

IncludedResource¶

SubscriptionResource¶

ServiceParameter¶

Period¶

Prices¶

PromotionInfo¶

Currency¶

SubscriptionFee¶

Discount¶

ResourceRateFee¶

FeeTier¶

SubscriptionPricing¶

Costs¶

SimpleCost¶

ResourceRateCost¶

TierCost¶

SubscriptionCosts¶

PaymentMethod¶