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
Payment Method Priorities
Limitations of Attached Payment Methods
Limitations on Spot Pricing
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",
      "required": true,
      "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"
      }
    },
    "billingPeriodAlignment": {
      "type": "string",
      "default": "SUBSCRIPTION_PERIOD_START",
      "enum": [
        "SUBSCRIPTION_PERIOD_START",
        "SUBSCRIPTION_PERIOD_EXPIRATION"
      ]
    },
    "autoRenewEnforcedUntilDate": {
      "type": "string",
      "format": "date"
    },
    "autoRenewEnforceEnabled": {
      "type": "boolean"
    }
  },
  "operations": {
    "getResources": {
      "path": "/resources",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "SubscriptionResource"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "getHistoricalResources": {
      "path": "/historicalResources",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "SubscriptionHistoricalResource"
        }
      },
      "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"
      }
    },
    "getTcvDetails": {
      "path": "/tcvDetails",
      "verb": "GET",
      "response": {
        "type": "SubscriptionTcvDetails"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "withCostOfBillingPeriod": {
          "kind": "query",
          "type": "boolean"
        }
      }
    },
    "getSubscriptionOperations": {
      "path": "/getSubscriptionOperations",
      "verb": "GET",
      "response": {
        "type": "SubscriptionAction"
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "getSubscriptionResourceOperations": {
      "path": "/getSubscriptionResourceOperations",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "SubscriptionResourceAction"
        }
      },
      "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
        }
      }
    },
    "putInMaintenance": {
      "path": "/putInMaintenance",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      }
    },
    "releaseFromMaintenance": {
      "path": "/releaseFromMaintenance",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      }
    },
    "getSpotPricing": {
      "path": "/specialPricing",
      "verb": "GET",
      "response": {
        "type": "SpecialPricing"
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "applySpotPricing": {
      "path": "/specialPricing",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      },
      "parameters": {
        "prices": {
          "kind": "body",
          "type": "SpecialPricing"
        }
      }
    },
    "resetSpotPricing": {
      "path": "/specialPricing",
      "verb": "DELETE",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false
      }
    },
    "getProviderCosts": {
      "path": "/providerCostHistory",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "ProviderCost"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "setProviderCosts": {
      "path": "/providerCostHistory",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "providerCosts": {
          "kind": "body",
          "type": "array"
        }
      }
    },
    "setProviderCostsForPeriod": {
      "path": "/providerCostHistory",
      "verb": "PUT",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "providerCosts": {
          "kind": "body",
          "type": "ProviderCosts"
        }
      }
    },
    "deleteProviderCost": {
      "path": "/providerCostHistory/{costId}",
      "verb": "DELETE",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "costId": {
          "kind": "path",
          "type": "integer"
        }
      }
    }
  },
  "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"
        }
      }
    },
    "SubscriptionResourceAction": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "required": true
        },
        "downsizeAllowed": {
          "type": "boolean"
        },
        "lowerLimit": {
          "type": "number"
        }
      }
    },
    "SubscriptionResource": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "description": "BSSResource APS ID",
          "required": true
        },
        "productId": {
          "type": "string",
          "description": "Product ID",
          "maxLength": 80
        },
        "MPNumber": {
          "type": "string",
          "description": "Manufacturer Part Number (MPN)",
          "maxLength": 250
        },
        "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"
        },
        "vendorSubscriptionId": {
          "type": "string"
        },
        "usage": {
          "type": "number"
        },
        "includedResources": {
          "type": "array",
          "items": {
            "type": "IncludedResource"
          }
        },
        "resourceOperations": {
          "type": "SubscriptionResourceAction"
        },
        "isDynamic": {
          "type": "boolean"
        },
        "consumptionType": {
          "type": "integer",
          "default": "0",
          "enum": [
            "0",
            "1",
            "2"
          ],
          "enumTitles": [
            "Unspecified",
            "Commitment",
            "Usage"
          ]
        }
      }
    },
    "ResourceHistory": {
      "type": "object",
      "properties": {
        "startDate": {
          "type": "string",
          "description": "Start date",
          "required": true
        },
        "endDate": {
          "type": "string",
          "description": "End date",
          "required": true
        },
        "amount": {
          "type": "number",
          "description": "Amount of units present during the period",
          "required": true
        }
      }
    },
    "SubscriptionHistoricalResource": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "integer",
          "description": "BSSResource ID",
          "required": true
        },
        "mpn": {
          "type": "string",
          "description": "MPN number",
          "required": true
        },
        "resourceUUID": {
          "type": "string",
          "description": "Resource UUID",
          "required": true
        },
        "history": {
          "type": "array",
          "description": "Resource history",
          "required": true,
          "items": {
            "type": "ResourceHistory"
          }
        }
      }
    },
    "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"
        },
        "priceTerm": {
          "type": "Period"
        }
      }
    },
    "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",
            "VOLUME_ORDER"
          ],
          "enumTitles": [
            "Flat price",
            "Tiered pricing at subscription level",
            "Volume pricing at subscription level",
            "Volume pricing at order level"
          ]
        },
        "price": {
          "type": "Currency"
        },
        "tiers": {
          "type": "array",
          "items": {
            "type": "FeeTier"
          }
        },
        "showZeroPrice": {
          "type": "boolean"
        },
        "chargePerUnit": {
          "type": "boolean"
        },
        "chargeForUpgrade": {
          "type": "boolean"
        },
        "discount": {
          "type": "Discount"
        },
        "priceTerm": {
          "type": "Period"
        }
      }
    },
    "FeeTier": {
      "type": "object",
      "properties": {
        "price": {
          "type": "Currency"
        },
        "lowerLimit": {
          "type": "number"
        },
        "discount": {
          "type": "Discount"
        },
        "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"
        }
      }
    },
    "ProviderCosts": {
      "type": "object",
      "properties": {
        "costs": {
          "type": "array",
          "items": {
            "type": "ProviderCost"
          }
        },
        "period": {
          "type": "Period"
        }
      }
    },
    "ResourceProviderCost": {
      "type": "object",
      "properties": {
        "cost": {
          "type": "Currency"
        },
        "resourceId": {
          "type": "string"
        },
        "priceTerm": {
          "type": "Period"
        }
      }
    },
    "SubscriptionPricing": {
      "type": "object",
      "properties": {
        "period": {
          "type": "Period"
        },
        "costs": {
          "type": "Prices"
        },
        "providerCosts": {
          "type": "ProviderCosts"
        },
        "prices": {
          "type": "Prices"
        }
      }
    },
    "Costs": {
      "type": "object",
      "properties": {
        "totalCost": {
          "type": "Currency"
        },
        "billingCurrencyCode": {
          "type": "string"
        },
        "exchangeRate": {
          "type": "number"
        },
        "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"
        }
      }
    },
    "CompositeId": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "required": true
        },
        "internalId": {
          "type": "integer"
        }
      }
    },
    "TcvDetails": {
      "type": "object",
      "properties": {
        "buyer": {
          "type": "CompositeId"
        },
        "seller": {
          "type": "CompositeId"
        },
        "startDate": {
          "type": "string",
          "format": "date"
        },
        "endDate": {
          "type": "string",
          "format": "date"
        },
        "currency": {
          "type": "string"
        },
        "planPeriod": {
          "type": "TcvPlanPeriodInfo"
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "TcvResourceInfo"
          }
        }
      }
    },
    "TcvPlanPeriodInfo": {
      "type": "object",
      "properties": {
        "period": {
          "type": "SubscriptionPeriod"
        }
      }
    },
    "TcvResourceInfo": {
      "type": "object",
      "properties": {
        "resource": {
          "type": "ResourceInfo"
        }
      }
    },
    "ResourceInfo": {
      "type": "object",
      "properties": {
        "id": {
          "type": "CompositeId"
        },
        "resourceName": {
          "type": "http://aps-standard.org/types/core/i18n/1.3#MLString",
          "description": "Resource name"
        }
      }
    },
    "SubscriptionTcvDetails": {
      "type": "object",
      "properties": {
        "subscription": {
          "type": "CompositeId"
        },
        "tcvs": {
          "type": "array",
          "items": {
            "type": "TcvDetails"
          }
        }
      }
    },
    "SubscriptionAction": {
      "type": "object",
      "properties": {
        "subscriptionUuid": {
          "type": "string",
          "required": true
        },
        "cancellationAllowed": {
          "type": "boolean"
        },
        "scheduledOrdersAllowed": {
          "type": "boolean"
        }
      }
    },
    "PaymentMethod": {
      "type": "object",
      "properties": {
        "paymentMethodId": {
          "type": "integer"
        }
      }
    },
    "AutoRenewalEnable": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "required": true
        }
      }
    },
    "PutOnHoldParameters": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "required": true,
          "enum": [
            "ACCOUNT_OVERDUE",
            "FRAUD",
            "CUSTOMER_REQUEST",
            "NOT_APPLICABLE",
            "AUP_VIOLATION",
            "OTHER"
          ]
        },
        "comment": {
          "type": "string",
          "required": true
        }
      }
    },
    "ReleaseFromHoldParameters": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "required": true,
          "enum": [
            "CUSTOMER_REQUEST",
            "RELEASED_FROM_CREDIT_HOLD",
            "NOT_APPLICABLE",
            "OTHER"
          ]
        },
        "comment": {
          "type": "string",
          "required": true
        }
      }
    },
    "SubscriptionPrice": {
      "type": "object",
      "properties": {
        "currencyId": {
          "type": "string"
        },
        "recurring": {
          "type": "number"
        },
        "transfer": {
          "type": "number"
        },
        "renewal": {
          "type": "number"
        },
        "setup": {
          "type": "number"
        },
        "recurringDiscountPercent": {
          "type": "number"
        },
        "renewalDiscountPercent": {
          "type": "number"
        },
        "setupDiscountPercent": {
          "type": "number"
        }
      }
    },
    "ResourceRate": {
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string"
        },
        "providerCost": {
          "type": "ProviderCost"
        },
        "prices": {
          "type": "ResourcePrice"
        },
        "costs": {
          "type": "ResourcePrice"
        }
      }
    },
    "ProviderCost": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "resourceId": {
          "type": "string"
        },
        "resource": {
          "type": "Resource"
        },
        "startDate": {
          "type": "string",
          "format": "date"
        },
        "currencyId": {
          "type": "string"
        },
        "amount": {
          "type": "number"
        }
      }
    },
    "ResourcePrice": {
      "type": "object",
      "properties": {
        "currencyId": {
          "type": "string"
        },
        "recurring": {
          "type": "number"
        },
        "recurringTiers": {
          "type": "array",
          "items": {
            "type": "Tier"
          }
        },
        "overuse": {
          "type": "number"
        },
        "setup": {
          "type": "number"
        },
        "setupTiers": {
          "type": "array",
          "items": {
            "type": "Tier"
          }
        },
        "overuseDiscountPercent": {
          "type": "number"
        },
        "recurringDiscountPercent": {
          "type": "number"
        },
        "setupDiscountPercent": {
          "type": "number"
        }
      }
    },
    "Tier": {
      "type": "object",
      "properties": {
        "lowerLimit": {
          "type": "number"
        },
        "price": {
          "type": "number"
        }
      }
    },
    "SpecialPricing": {
      "type": "object",
      "properties": {
        "applicableTo": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "creationDate": {
          "type": "string",
          "format": "date"
        },
        "prices": {
          "type": "SubscriptionPrice"
        },
        "costs": {
          "type": "SubscriptionPrice"
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "ResourceRate"
          }
        }
      }
    },
    "Resource": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "internalId": {
          "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	DEFAULT	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.
billingPeriodAlignment	Enum	Not Required	SUBSCRIPTION_PERIOD_START	Returns billing period alignment.
autoRenewEnforcedUntilDate	String	Not Required		The date is to to restrict the resellers/customers from disabling auto renewal until the 3 year commitment is completed
autoRenewEnforceEnabled	Boolean	Not Required

Relationship ¶

NAME	TYPE	REQUIRED	DESCRIPTION
account	PAAccount	Yes	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.
getHistoricalResources	GET	/historicalResources	Collection of SubscriptionHistoricalResource	Get all the resources from the subscription along with their history.
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.
getTcvDetails	GET	/tcvDetails	SubscriptionCosts structure	This operation enables a reseller to get the total contract values and the costs details on the subscription recurring fees.
getSubscriptionOperations	GET	/getSubscriptionOperations		GetSubscriptionOperations.
getSubscriptionResourceOperations	GET	/getSubscriptionResourceOperations		GetSubscriptionResourceOperations.
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.
putInMaintenance	POST	/putInMaintenance		This operation puts the subscription in maintenance status. No changes can be performed to subscription in this status, no order can be created, subscription is not being billed.
releaseFromMaintenance	POST	/releaseFromMaintenance		This operation releases the subscription from maintenance status.
getSpotPricing	GET	/specialPricing	SpecialPricing structure	Return applied special prices and costs and effective provider spot costs to given subscription if there is any
applySpotPricing	POST	/specialPricing	Void.	Apply provided special prices and costs and provider spot costs to given subscription
resetSpotPricing	DELETE	/specialPricing	Void.	Reset/detach from given subscription applied special prices and costs if there is any Provider spot costs being applied to subscription are affected
getProviderCosts	GET	/providerCostHistory	ProviderCost structure rray	Get history of Provider Spot Costs being applied to the subscription
setProviderCosts	POST	/providerCostHistory	Void.	Create new Provider Spot Costs for given subscription
setProviderCostsForPeriod	PUT	/providerCostHistory	Void.	Create new Provider Spot Costs on provided period
deleteProviderCost	DELETE	/providerCostHistory/{costId}	Void.	Delete a certain Provider Spot Cost record

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

getTcvDetails¶

HTTP Request

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

Description

This operation enables a reseller to get the total contract values and the costs details on the subscription recurring fees.

Parameters

PARAMETER	TYPE	DESCRIPTION
withCostOfBillingPeriod	Boolean

Returns

SubscriptionCosts structure

getSubscriptionOperations¶

HTTP Request

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

Description

GetSubscriptionOperations.

Returns

getSubscriptionResourceOperations¶

HTTP Request

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

Description

GetSubscriptionResourceOperations.

Returns

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.

putInMaintenance¶

HTTP Request

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

Description

This operation puts the subscription in maintenance status. No changes can be performed to subscription in this status, no order can be created, subscription is not being billed.

Returns

releaseFromMaintenance¶

HTTP Request

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

Description

This operation releases the subscription from maintenance status.

Returns

getSpotPricing¶

HTTP Request

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

Description

Return applied special prices and costs and effective provider spot costs to given subscription if there is any

Returns

SpecialPricing structure

applySpotPricing¶

HTTP Request

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

Description

Apply provided special prices and costs and provider spot costs to given subscription

Parameters

PARAMETER	TYPE	DESCRIPTION
prices	SpecialPricing	SpecialPricing structure

Returns

Void.

resetSpotPricing¶

HTTP Request

DELETE /aps/2/resources/{aps-id}/specialPricing

Description

Reset/detach from given subscription applied special prices and costs if there is any Provider spot costs being applied to subscription are affected

Returns

Void.

getProviderCosts¶

HTTP Request

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

Description

Get history of Provider Spot Costs being applied to the subscription

Returns

ProviderCost structure rray

setProviderCosts¶

HTTP Request

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

Description

Create new Provider Spot Costs for given subscription

Parameters

PARAMETER	TYPE	DESCRIPTION
providerCosts	Array	ProviderCost structure array

Returns

Void.

setProviderCostsForPeriod¶

HTTP Request

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

Description

Create new Provider Spot Costs on provided period

Parameters

PARAMETER	TYPE	DESCRIPTION
providerCosts	ProviderCosts	ProviderCosts structure

Returns

Void.

deleteProviderCost¶

HTTP Request

DELETE /aps/2/resources/{aps-id}/providerCostHistory/{costId}

Description

Delete a certain Provider Spot Cost record

Parameters

PARAMETER	TYPE	DESCRIPTION
costId	Integer

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.

SubscriptionResourceAction¶

NAME	TYPE	ATTRIBUTES
resourceId	String	Required
downsizeAllowed	Boolean	Not Required
lowerLimit	Number	Not Required

SubscriptionResource¶

Subscription resource information

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
resourceId	String	Required		APS ID of corresponding BSSResource.
productId	String	Not Required		Unique Product ID
MPNumber	String	Not Required		Manufacturer Part Number (MPN)
internalResourceId	Integer	Required		The platform internal resource ID.
status	Enum	Not Required		The resource status.
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.
vendorSubscriptionId	String	Not Required		The vendor subscription id
usage	Number	Not Required		The current resource usage.
includedResources	Array of IncludedResource	Not Required		The set of resources inside a composite resource.
resourceOperations	SubscriptionResourceAction	Not Required		The resource operations.
isDynamic	Boolean	Not Required
consumptionType	Integer	Not Required	0	The resource consumption type.

ResourceHistory¶

NAME	TYPE	ATTRIBUTES
startDate	String	Required
endDate	String	Required
amount	Number	Required

SubscriptionHistoricalResource¶

NAME	TYPE	ATTRIBUTES
resourceId	Integer	Required
mpn	String	Required
resourceUUID	String	Required
history	Array of ResourceHistory	Required

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¶

Resource identification structure.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
unit	Enum	Not Required
duration	Integer	Not Required

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.
priceTerm	Period	Not Required	The price term period.

Discount¶

The structure of applicable discount.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
type	Enum	Not Required	Specifies the discount type.
value	Number	Not Required	The discount value.
amount	Number	Not Required	The 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.
priceTerm	Period	Not Required	The price term period.

FeeTier¶

This structure contain information about resource tier limit

NAME	TYPE	ATTRIBUTES
price	Currency	Not Required
lowerLimit	Number	Not Required
discount	Discount	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

ProviderCosts¶

Provider Spot Costs structure.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
costs	Array of ProviderCost	Not Required		Get list of provider spot costs
period	Period	Not Required

ResourceProviderCost¶

NAME	TYPE	ATTRIBUTES	DESCRIPTION
cost	Currency	Not Required	The cost of a subscription item.
resourceId	String	Not Required	The APS ID of the BSSResource.
priceTerm	Period	Not Required	The price term period.

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.
providerCosts	ProviderCosts	Not Required	When requested by a provider or l1 reseller, this is the subscription provider cost details estimated for the specified customer. Customers cannot request the provider costs.
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.
billingCurrencyCode	String	Not Required	Currency that will be used to bill account.
exchangeRate	Number	Not Required	Current exchange rate from subscription cost currency to billing currency.
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.

CompositeId¶

The structure that defines the composite identifier for the object.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
id	String	Required		The APS UUID of the object.
internalId	Integer	Not Required		The internal Id of the object.

TcvDetails¶

The total contract values for the subscription period and costs for the billing period for one level of the vendors chain

NAME	TYPE	ATTRIBUTES	DESCRIPTION
buyer	CompositeId	Not Required	The composite identifier for the buyer account for corresponding level.
seller	CompositeId	Not Required	The composite identifier for the seller account for corresponding level.
startDate	String	Not Required	The start date of the subscription period for which the total contract values are calculated.
endDate	String	Not Required	The end date of the subscription period for which the total contract values are calculated.
currency	String	Not Required	The currency code for the corresponding level.
planPeriod	TcvPlanPeriodInfo	Not Required	The subscription TCV and cost excluding the cost for additional resources amount.
resources	Array of TcvResourceInfo	Not Required	The TCV and costs for all additional resources.

TcvPlanPeriodInfo¶

The TCV and costs for the plan-period for the corresponding level

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
period	SubscriptionPeriod	Not Required		The subscription period for which the total contract values are calculated.

TcvResourceInfo¶

The TCV and costs for the resource for the corresponding level

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
resource	ResourceInfo	Not Required		General resource information

ResourceInfo¶

General resource information

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
id	CompositeId	Not Required		The composite identifier of the resource.
resourceName	I18n	Not Required		The resource name in the multilingual format.

SubscriptionTcvDetails¶

The subscription Total contract value details.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
subscription	CompositeId	Not Required		The composite identifier for the subscription.
tcvs	Array of TcvDetails	Not Required		The total contract values and costs for the billing period for each level of the vendors chain

SubscriptionAction¶

NAME	TYPE	ATTRIBUTES
subscriptionUuid	String	Required
cancellationAllowed	Boolean	Not Required
scheduledOrdersAllowed	Boolean	Not Required

PaymentMethod¶

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
paymentMethodId	Integer	Not Required

AutoRenewalEnable¶

Defines whether the subscription auto-renewal is enabled.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
enabled	Boolean	Required		If true, it enables the subscription auto-renewal process.

PutOnHoldParameters¶

The set of parameters used when putting a subscription on hold.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
reason	Enum	Required		The reason of putting the subscription on hold PutOnCreditHoldReason.
comment	String	Required		The comment on the reason of putting the subscription on hold.

ReleaseFromHoldParameters¶

The set of parameters used when releasing a subscription from the hold.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
reason	Enum	Required		The reason to release the subscription from hold ReleaseFromCreditHoldReason.
comment	String	Required		The comment on the reason to release the subscription from hold.

SubscriptionPrice¶

The subscription price structure.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
currencyId	String	Not Required	Subscription currency ISO code
recurring	Number	Not Required	Subscription recurring fee
transfer	Number	Not Required	Subscription transfer fee
renewal	Number	Not Required	Subscription renewal fee
setup	Number	Not Required	Subscription setup fee
recurringDiscountPercent	Number	Not Required	Recurring Margin (percents)
renewalDiscountPercent	Number	Not Required	Renewal Margin (percents)
setupDiscountPercent	Number	Not Required	Setup Margin (percents)

ResourceRate¶

The resource rate structure.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
resourceId	String	Not Required	Resource internal ID
providerCost	ProviderCost	Not Required	Vendor’s resource price
prices	ResourcePrice	Not Required	Customer’s resources prices
costs	ResourcePrice	Not Required	Vendor’s resources costs

ProviderCost¶

The resource vendor price structure.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
id	Integer	Not Required
resourceId	String	Not Required
resource	Resource	Not Required
startDate	String	Not Required	Resource provider cost effective date
currencyId	String	Not Required	Subscription currency ISO code
amount	Number	Not Required	Resource provider cost

ResourcePrice¶

The resource price structure.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
currencyId	String	Not Required	Subscription currency ISO code
recurring	Number	Not Required	Resource recurring fee
recurringTiers	Array of Tier	Not Required	Tier levels for recurring volume special pricing
overuse	Number	Not Required	Resource overuse fee
setup	Number	Not Required	Resource setup fee
setupTiers	Array of Tier	Not Required	Tier levels for setup volume special pricing
overuseDiscountPercent	Number	Not Required	Overuse Margin (percents)
recurringDiscountPercent	Number	Not Required	Recurring Margin (percents)
setupDiscountPercent	Number	Not Required	Setup Margin (percents)

Tier¶

Single volume level with effective price

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
lowerLimit	Number	Not Required		Amount after that price is getting effective.
price	Number	Not Required		Effective price that will be used in calculations.

SpecialPricing¶

Spot pricing structure.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
applicableTo	Array of String	Not Required	Applicability.
creationDate	String	Not Required	Special pricing applicability time, output only property
prices	SubscriptionPrice	Not Required	Customer’s prices
costs	SubscriptionPrice	Not Required	Vendor’s costs
resources	Array of ResourceRate	Not Required	Customer’s resources prices & vendor’s resources costs

Resource¶

Resource identification structure.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
id	String	Not Required		The resource UUID
internalId	Integer	Not Required		The resource internal ID

Payment Method Priorities ¶

When there is a choice of various payment methods, the selection of a payment method in an order for a certain subscription is based on the following priority list (the highest priority is on top):

The payment method explicitly specified in the order takes precedence over all others.
The payment method attached to the subscription takes precedence over the account default payment method in operations with this subscription.
The account default payment method is applied to the order if none of the above payment methods is discovered.

Limitations of Attached Payment Methods ¶

An attached payment method can be used in orders and invoices dealing with an existing subscription that it is attached to. This causes the following limitations:

Attached payment methods cannot be used in sales orders, because the latter create new subscriptions.
To pay an invoice consolidating one or more orders related to one or more subscriptions, payment methods attached to the involved subscriptions cannot be used. Such an invoice is paid either automatically by the account default payment method or by a payment method assigned by the account staff manually.
When a billing order includes more than one subscription, a payment method is selected similar to the previous item.

Limitations on Spot Pricing ¶

When using the /aps/2/resources/<sub-id>/specialPricing endpoint to manage spot pricing, keep in mind the privilege rules. Following these rules, a reseller can change subscription prices for their subordinate accounts, for example:

An L2 reseller can set spot prices for subscriptions of their direct customers, but cannot set their own costs for those subscriptions.
In the above example, the L1 reseller, who is the L2 reseller’s parent, can set both spot prices for the customer and spot costs for the L2 reseller.

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
Spot Pricing

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.

Spot Pricing ¶

To change prices for an existing subscription, this APS type exposes three operations with spot prices demonstrated in this section. When using spot prices, keep in mind the sales chain:

Service Vendor > Provider > Reseller > Customer

The provider can change the prices (how much the customer pays to the reseller) and costs (how much the reseller pays to the provider) for an existing subscription that a customer purchased from a reseller. In general, those costs and prices are called “spot prices” here.

To apply spot prices to a subscription, call the applySpotPricing operation as in this example:

POST /aps/2/resources/f6af7a84-c9d1-40f0-b686-762112c1e40e/specialPricing

{  "resources":
  [
    {
      "resourceId": "94d2fbc6-b991-49d7-9122-6c807d4e08df",
      "prices":{
            "recurring": 7.0

      },
      "costs":{
        "recurring": 6.0
      }
    }
  ],
  "prices":{
    "recurring": 4.0,
    "renewal":4.0,
    "setup": 4.0
  },
  "costs":{
    "recurring": 3.0,
    "renewal": 3.0,
    "setup": 3.0
  },
  "applicableTo":[
    "RENEWAL"
  ]
}

If successful, the response is HTTP/1.1 204 No Content.

Keys:

Spot prices for a resource rate are counted per resource unit as specified in the respective service plan.
The recommended values for the applicableTo property are the following:
- []: the empty array means the spot prices affect only change and billing orders created during the current subscription period after those prices are applied to the subscription.
- [‘RENEWAL’]: the spot prices affect change, billing, and renewal orders created after those prices are applied to the subscription.

Note

For change orders used to upsize a resource after spot prices are assigned to that resource, the new spot prices are assigned immediately to the ordered amount of the resource. For change orders used to downsize a resource, the refund for the unused resource amount is based on the real price paid for that amount.

To check whether a subscription billing is based on spot prices, use the getSpotPricing operation, as in this example:

GET /aps/2/resources/f6af7a84-c9d1-40f0-b686-762112c1e40e/specialPricing

If spot prices or costs are assigned to this subscription, the response looks similar to the following:

HTTP/1.1 200 OK

{
  "applicableTo": [
    "RENEWAL",
    "SALES"
  ],
  "creationDate": "2020-04-16",
  "prices": {
    "recurring": 4.0,
    "transfer": 0.0,
    "renewal": 4.0,
    "setup": 4.0
  },
  "costs": {
    "recurring": 3.0,
    "transfer": 0.0,
    "renewal": 3.0,
    "setup": 3.0
  },
  "resources": [
    {
      "resourceId": "94d2fbc6-b991-49d7-9122-6c807d4e08df",
      "prices": {
        "recurring": 7.0,
        "overuse": 0.0,
        "setup": 0.0
      },
      "costs": {
        "recurring": 6.0,
        "overuse": 0.0,
        "setup": 0.0
      }
    }
  ]
}

If there are no spot prices assigned to the subscription, the platform returns HTTP/1.1 204 No Content.

To detach spot prices from a subscription, call the resetSpotPricing operation as in this example:

DELETE /aps/2/resources/f6af7a84-c9d1-40f0-b686-762112c1e40e/specialPricing

If successful, the platform returns HTTP/1.1 204 No Content.

When using the above examples, follow the Limitations on Spot Pricing.

← BSSResource

BssAccountInformation →

CloudBlue Commerce API

Previous topic

Next topic

BSSSubscription¶

getResources¶

getHistoricalResources¶

getServiceParameters¶

getPrices¶

updatePrices¶

getCosts¶

getTcvDetails¶

getSubscriptionOperations¶

getSubscriptionResourceOperations¶

setPaymentMethods¶

getPaymentMethods¶

autoRenew¶

putOnAdministrativeHold¶

putOnCreditHold¶

releaseFromAdministrativeHold¶

releaseFromCreditHold¶

putInMaintenance¶

releaseFromMaintenance¶

getSpotPricing¶

applySpotPricing¶

resetSpotPricing¶

getProviderCosts¶

setProviderCosts¶

setProviderCostsForPeriod¶

deleteProviderCost¶

SubscriptionPeriod¶

BillingTerms¶

BillingPeriod¶

AutoRenewal¶

Attribute¶

IncludedResource¶

SubscriptionResourceAction¶

SubscriptionResource¶

ResourceHistory¶

SubscriptionHistoricalResource¶

ServiceParameter¶

Period¶

Prices¶

PromotionInfo¶

Currency¶

SubscriptionFee¶

Discount¶

ResourceRateFee¶

FeeTier¶

DiscountTier¶

ProviderCosts¶

ResourceProviderCost¶

SubscriptionPricing¶

Costs¶

SimpleCost¶

ResourceRateCost¶

TierCost¶

SubscriptionCosts¶

CompositeId¶

TcvDetails¶

TcvPlanPeriodInfo¶

TcvResourceInfo¶

ResourceInfo¶

SubscriptionTcvDetails¶

SubscriptionAction¶

PaymentMethod¶

AutoRenewalEnable¶

PutOnHoldParameters¶

ReleaseFromHoldParameters¶

SubscriptionPrice¶

ResourceRate¶

ProviderCost¶

ResourcePrice¶

Tier¶

SpecialPricing¶

Resource¶