Manage Orders

The BSS API allows an external system to issue and activate various types of orders to perform some commercial operations, including creation or cancellation of subscriptions, ordering more resources, and so on.

APS Type and Operations

The platform uses the OrderManagement APS type to create a singleton APS resource presenting the order management service that provides several custom operations to manage orders in BSS. This document considers the following custom operations:

• orderInfo - get a list of orders or some data of a specified order by sending a GET request.
• placeOrder - create an order by sending a POST request. The type of a new order must be specified by the mandatory type property in the request body.
• estimateOrder - allows the provider or a reseller to estimate price details of an order without placing that order.

Regardless of the order type in the placeOrder request, on success, the APS controller returns the APS ID of the new order, for example:

{
   "orderId": "f0817852-282c-4047-a4d3-f6501939d5a6"
}

Sales Order

A sales order is the only order type that creates a subscription from a service plan for a specified customer. In a POST request body, this is defined as "type":"SALES".

The procedure consists of the following steps:

1. Identify a customer - find out the APS ID of the account who you want to subscribe to the selected service plans.
2. Identify service plans - find out the APS IDs of the required service plans, subscription periods, and add-on resources to purchase.
3. Identify a payment method - from the available payment methods that the chosen account owns, select the one that will be applied to the new order.
4. Create a sales order - request a new sales order with input parameters discovered in the previous steps. If all is OK, the platform creates a sales order and starts the order processing.
5. Verify the order status - get the order details to verify if the ordered services are provisioned for the customer.

Other Order Types

There are several order types that change a subscription. In a POST request body, an order type is specified by the type property:

• RENEWAL - create a renewal order for a specified subscription and start the renewal process for the next subscription period.
• CHANGE - create a change order to switch a subscription to another period of a specified service plan or to change resource limits in the subscription.
• CANCELLATION - create a cancellation order to cancel a specified subscription.

Since the main object in those orders is an existing subscription, the order management sequence is a bit different from the case with a sales order.

The procedure consists of the following steps:

1. Identify a customer - find out the APS ID of the account whose subscription you want to change.
2. Identify a subscription - find out the APS ID of the subscription to be changed, and, if necessary, the subscription period that must be changed.
3. Identify a payment method - from the available payment methods that the chosen account owns, select the one that will be applied to the new order.
4. Create an order - request a new order with input parameters discovered in the previous steps. If all is OK, the platform creates the order and starts the order processing.
5. Verify the order status - get the order details to verify if the ordered updates in the specified subscription are completed.

Security

To be able to call the above-mentioned custom operations, an external system must be authorized to use the GET and POST methods on the OrderManagement APS type whose APS ID is http://www.odin.com/billing/order-management. To add this permission, follow the Set up User’s Credentials section.

Order Processing

After an order that requires payment from an account (customer or reseller) is placed in BSS, the latter starts the order processing that consists of at least the following phases:

1. Order payment.

   This phase requires the account to have an automated payment method, for example, a bank card. The paymentMethodId property, if used, specifies a payment method explicitly. Otherwise, the platform will seek for the default payment method (marked as Auto Payments) for that account. When you verify an order status, pay attention to the returned paymentStatus property that shows if the order is payed or there are some issues with it.

   Warning

   If the platform cannot find a relevant payment method, it places the required order without a payment attached.

2. Order provisioning.

   BSS creates a subscription and requires the provisioning system, usually OSS, to perform a required operation, for example, provisioning of the services marked as “auto-provisioning”. When you verify an order status, pay attention to the returned provisioningStatus property that shows if the ordered services were provisioned successfully or there were some issues with it.

When creating an order, it might be necessary to pass the following optional properties:

• paymentMethodId is the platform internal ID of a payment method belonging to the customer for whom an order is requested. This method will be used to pay the requested order. If this property is omitted, the platform will be seeking for a method declared as default for the customer.
• attributes is an array of BSS specific order attributes preliminary configured by the provider as custom attributes in the platform. Each entry is a pair of attributeID and value properties.
• parameters are also known as activation parameters. You should send such parameters when creating a sales order in a case the ordered services require those parameters at the provisioning stage.

Source Data

Depending on the order type, an external system must preliminary collect the following data before sending REST requests:

• The following properties of the service plan if you want to order it:
  • APS ID of the service plan
  • A subscription period identified by its length consisting of the measurement unit, typically “MONTHS” or “YEARS”, and the number of the units
  • APS ID of the resources if you want to order more amount of those resources than the service plan includes
• APS ID of the account if you want to subscribe the latter to a service plan
• APS ID of the subscription if you want to manage a subscription, for example, to renew, switch or cancel it

Identify and Configure Account

Identify an account that you want to subscribe to service plans or an account whose subscription you are going to change.

An order must specify the APS ID of the account to be subscribed to service plans or the account whose subscription must be changed.

Find out the APS ID of the account as explained in the Account Lookup section, for example:

GET /aps/2/collections/accounts?eq(id,1000001)

Pay attention to the aps section in the response:

HTTP/1.1 200 OK

[{
   "aps": {
      "id": "d7dd06ef-20a0-41f5-b89f-768ef373ae44",
      "type": "http://parallels.com/aps/types/pa/account/1.2",
      "status": "aps:ready",
      ...
   },
   ...
}]

If you want the order to be paid automatically, ensure the account has an automatic payment method, like a bank card, configured as the default method (marked as Auto Payments):

Note

If a request for order creation does not specify a payment method, the order management service will try to apply the payment method configured as default (marked as Auto Payments). This requires the customer to have a payment method configured as default.

Identify Service Plans

To subscribe an account to service plans, identify them first.

Get a list of service plans as explained in the Service Plan section, for example:

GET /aps/2/collections/service-plans

In the response, find out the service plans and subscription periods you want to order as well as the resources that you can buy in addition to the included amount:

HTTP/1.1 200 OK

[
   ...
   {
      "aps": {
         "id": "ebf17799-6a39-4133-ab9c-0afa40dcd6ae",
         "type": "http://www.odin.com/billing/ServicePlan/1.0",
         "status": "aps:ready",
         ...
      },
      "name": {
         "en_US": "VPS Demo Services"
      },
      "billingTerms": {
         "autorenewal": {
            "days": 0,
            "type": "DISABLED"
         },
         "model": "CHARGE_BEFORE_BILLING_PERIOD",
         "period": {
            "duration": 1,
            "unit": "MONTHS"
         },
         "recurringPricesEvery": "MONTH"
      },
      "subscriptionPeriods": [
         {
            "autoRenewalPeriod": {
               "unit": "MONTHS",
               "duration": 1
            },
            "numberOfBillingPeriods": 1,
            "trial": false,
            "defaultPeriod": false,
            "fees": {
               "setup": {
                  "price": {
                     "value": "2.0",
                     "code": "USD"
                  },
                  ...
               },
               "recurring": {
                  "price": {
                     "value": "4.25",
                     "code": "USD"
                  },
                  ...
               },
               "renewal": {
                  "price": {
                     "value": "2.0",
                     "code": "USD"
                  },
                  ...
               },
               "deposit": { ... },
            },
            "refund": { ... }
         },
         ...
      ],
      "resourceRates": [
         {
            "resourceId": "2f8905f8-4302-49d7-ab7f-65c9036addf0",
            ...
            "units": {
               "included": 1.0,
               "min": 1.0,
               "max": 1000.0
            },
            "fees": {
               "setup": {
                  "price": {
                     "value": "0.0",
                     "code": "USD"
                  },
                  ...
               },
               "recurring": {
                  "price": {
                     "value": "1.0",
                     "code": "USD"
                  },
                  "chargePerUnit": true,
                  ...
               }
            },
            ...
         },
         {
            "resourceId": "bf8ea705-3f2b-4f3c-b445-a11ec100da82",
            ...
            "units": {
               "included": 0.0,
               "min": 0.0,
               "max": -1.0
            },
            "fees": {
               "setup": {
                  "price": {
                     "value": "0.0",
                     "code": "USD"
                  },
                  ...
               },
               "recurring": {
                  "price": {
                     "value": "1.5",
                     "code": "USD"
                  },
                  "chargePerUnit": true,
                  ...
               }
            },
            ...
         },
         ...
      ],
      ...
   },
   ...
]

The returned service plan representation contains the APS ID (aps.id) of the plans as well as the subscription periods identified by the measurement unit (subscriptionPeriods.autoRenewalPeriod.unit) and the number of the units (subscriptionPeriods.autoRenewalPeriod.duration). A list of resource rates allows a customer or a system to order more amount of resources than the service plan includes.

Identify Payment Method

Find out a payment method to pay a new order.

Get a list of payment methods owned by the account as explained in the Get Payment Methods section, for example:

GET /aps/2/services/payment-method-manager/paymentMethods?accountId=d7dd06ef-20a0-41f5-b89f-768ef373ae44

In the response, find out the id property of the payment method bo be applied to the new order:

[
   {
      "id": 11,
      "paymentSystemId": "Visa",
      "paymentSystem": "Visa",
      "ownerAccountId": "d7dd06ef-20a0-41f5-b89f-768ef373ae44",
      "number": "****1111",
      "name": "Visa ****1111",
      "type": "CREDIT_CARD",
      "perCustomer": true,
      "status": "ACTIVE",
      "ratified": "NOT_REQUIRED",
      "defaultMethod": true
   },
   {
      "id": 0,
      "paymentSystemId": "Check/Cash",
      "paymentSystem": "Check/Cash",
      "ownerAccountId": null,
      "number": null,
      "name": "Check/Cash",
      "type": "MANUAL",
      "perCustomer": false,
      "status": "ACTIVE",
      "ratified": "NOT_REQUIRED",
      "defaultMethod": false
   }
]

Get Terms and Conditions of Service Plans

Since usually service plans are accompanied with certain terms and conditions that must be accepted by a customer, a requester can get the contents of those terms and conditions before subscribing that customer to the service plan. The request must contain APS IDs of the service plans and the customer as in the following example:

POST /aps/2/services/order-manager/orders/termsconditions

{
   "type": "SALES",
   "accountId": "d7dd06ef-20a0-41f5-b89f-768ef373ae44",
   "products": [
      {
         "planId": "ebf17799-6a39-4133-ab9c-0afa40dcd6ae",
         "period": {
               "unit": "MONTHS",
               "duration": 1
         }
      }
   ]
}

If there are the requested terms and conditions, the platform returns their IDs and contents:

[
   {
      "termId": "1",
      "name": "Terms and Conditions",
      "content": "<h1>Cloud SaaS</h1>\r\n<h2>Introduction</h2>\r\n
            Lorem ipsum ut porttitor sagittis.\r\n
            <h2>Intellectual Properties</h2>\r\n
            Convallis interdum porttitor ante hendrerit.\r\n
            <h2>Restrictions</h2>\r\n
            Ac auctor duis curae magna."
   }
]

When placing a sales order to subscribe a customer to the service plans, the request must confirm the acceptance of the respective terms and conditions.

Sales Order

To subscribe a customer to a list of service plans, an external management system must request the creation of a sales order in the platform.

In a request, specify the parameters you have collected in the previous steps. Optionally, the request can contain the following groups of properties:

• If you want your customer to have more resources than assigned by the units.included values in the resourceRates array of a service plan, add the resources array containing a pair of the APS ID and total amount for every such resource.
• To pass activation parameters, required by the ordered application services, add them inside the parameters array.
• To assign order attributes, send those attributes inside the attributes array.
• To accept terms and conditions required by the service plans, send the acceptedTerms array containing the IDs of the accepted terms and conditions.

The following example illustrates how to subscribe a specified customer to a list of specified service plans and demonstrates a request for an extended amount of a resource:

POST /aps/2/services/order-manager/orders

{
   "type": "SALES",
   "accountId": "d7dd06ef-20a0-41f5-b89f-768ef373ae44",
   "paymentMethodId": "11",
   "products": [
      {
         "planId": "ebf17799-6a39-4133-ab9c-0afa40dcd6ae",
         "period": {
               "unit": "MONTHS",
               "duration": 1
         },
         "resources": [
            {
               "resourceId": "2f8905f8-4302-49d7-ab7f-65c9036addf0",
               "amount": 20
            },
            {
               "resourceId": "bf8ea705-3f2b-4f3c-b445-a11ec100da82",
               "amount": 10
            }
         ],
         "parameters": [
            {
               "aps": {
                  "type": "http://aps-standard.org/samples/vpsdemo/management/1.0"
               },
               "client": "1st APS, inc.",
               "mail": "jsmith@aps.test"
            }
         ],
         "childProducts": [
            { // Another service plan - upsell
            }
         ]
      },
      { // Another service plan
      }
   ],
   "attributes": [
      {
         "attributeID": "comments",
         "value": "Requested by the ERP system."
      }
   ],
   "acceptedTerms": [
      "1"
   ],
   "specialPricing" : { // See the Set Special Prices section for details
   }
}

Keynotes:

• For every service plan specified in the request, a separate subscription must be created on completion of the order processing.
• In the resources set, a required resource amount must be higher than the included amount of the resource, since the former includes the latter plus additional amount.
• An entry in the parameters array contains a set of properties required by an auto-provisioning APS resource whose APS type is specified by the aps section.
• Refer to the Set Special Prices section for details about special prices.

The response must contain the APS ID of the created order, as specified earlier in the APS Type and Operations section.

If all is configured correctly, the platform will process the created sales order, including:

• Order payment
• Creation of the customer subscription
• Provisioning of the services

In BSS, you can verify if a subscription is created from the requested service plan for the specified account:

The total amount of the ordered resource in the subscription is exactly the same as requested, that is 20:

To get the APS IDs of the subscriptions related to a particular order, refer to the Get List of Orders process.

Identify Subscription

To change a subscription, find out its APS ID, subscription period and resources to be changed.

You can search for a subscription using various ways as in the following examples.

• Get the full list of subscriptions:

  GET /aps/2/collections/subscriptions
  

• Get all subscriptions of a customer using the subscriptions link of the account APS type:

  GET /aps/2/resources/d7dd06ef-20a0-41f5-b89f-768ef373ae44/subscriptions
  

Find out the subscription you want to process (for example, to renew or cancel) in the response that will look similar to the following:

HTTP/1.1 200 OK

[
   {
      "aps": {
                     "id": "4c867c87-fbf7-49e8-9f7e-0d06e8f7a003",
                     "type": "http://parallels.com/aps/types/pa/subscription/1.0",
                     "status": "aps:ready",
         ...
      },
      "description": "",
      "disabled": false,
      "name": "Cloud VPS Services",
      "trial": false,
      "serviceTemplateId": 3,
      "subscriptionId": 1000001
   },
   ...
]

Renewal Order

When a subscription is coming up to its expiration date, the platform will renew it automatically for the next subscription period if the subscription configuration inherited from the service plan allows it. Alternatively, a staff member or an external management system can renew the subscription period including the upgrade of the subscription from a trial period to a paid period.

To renew a subscription, an external management system must call the placeOrder custom operation as in the following example:

POST /aps/2/services/order-manager/orders

{
   "type": "RENEWAL",
   "subscriptionId": "4c867c87-fbf7-49e8-9f7e-0d06e8f7a003",
   "paymentMethodId": "11",
   "period": {
      "unit": "MONTHS",
      "duration": 1
   }
}

Note

The period structure is needed only if you are going to change the period, otherwise the subscription will be renewed for the next period equal the current period.

The response must contain the APS ID of the created order, as specified earlier in the APS Type and Operations section.

Change Order

A change order allows a requester either to switch a subscription or to change resource limits in a subscription as explained in the following two sections.

Switching Subscription

The platform allows switching a subscription from its current service plan to another one or to another subscription period within the current service plan. An external management system can call the placeOrder custom operation to start a switching process.

POST /aps/2/services/order-manager/orders

{
   "type": "CHANGE",
   "subscriptionId": "4c867c87-fbf7-49e8-9f7e-0d06e8f7a003",
   "planId": "ebf17799-6a39-4133-ab9c-0afa40dcd6ae",
   "paymentMethodId": "11",
   "period": {
      "unit": "MONTHS",
      "duration": 3
   }
}

Note

The planId property is needed only if you are going to change the subscription for another service plan, otherwise only the subscription period will be changed within the current service plan.

On success, the response must contain the APS ID of the created order, as specified earlier in the APS Type and Operations section.

Changing Resource Limits

To buy additional amount of resources within a subscription, an external management system can call the placeOrder custom operation as in the following example:

POST /aps/2/services/order-manager/orders

{
   "type": "CHANGE",
   "subscriptionId": "4c867c87-fbf7-49e8-9f7e-0d06e8f7a003",
   "paymentMethodId": "11",
   "resources": [
      {
         "resourceId": "bf8ea705-3f2b-4f3c-b445-a11ec100da82",
         "amountChange": 10
      }
   ]
}

Every entry in the resources array corresponds to a resource rate in the respective service plan and consists of the resource APS ID and a change of the resource limit. The change can be either a positive number (to increase the limit) or negative (to decrease the limit).

On success, the response must contain the APS ID of the created order, as specified earlier in the APS Type and Operations section.

Cancellation Order

A cancellation order is used to request the termination of a subscription.

To cancel a subscription, an external management system must call the placeOrder custom operation as in the following example:

POST /aps/2/services/order-manager/orders

{
   "type": "CANCELLATION",
   "subscriptionId": "4c867c87-fbf7-49e8-9f7e-0d06e8f7a003"
}

On success, the response must contain the APS ID of the created order, as specified earlier in the APS Type and Operations section.

Get List of Orders

Typically, an external management system verifies if the placed orders were processed successfully.

Get All Orders

An external management system can get a list of orders by calling the listOrders custom operation:

GET /aps/2/services/order-manager/orders

The response contains a list of orders:

HTTP/1.1 200 OK

[
   {
      "orderId": "18131926-c152-4652-8a29-3fe076929f4b",
      "orderNumber": "SO000014",
      "type": "SO",
      "status": "COMPLETED",
      "paymentStatus": "FINISHED",
      "provisioningStatus": "COMPLETED",
      "ofStatus": "CP",
      "sellerId": "c0d43087-da72-472a-a176-84a34608979f",
      "buyerId": "d7dd06ef-20a0-41f5-b89f-768ef373ae44",
      "orderDate": "2018-04-04T21:00:00Z",
      "expirationDate": "2018-04-07T21:00:00Z",
      "creationTime": "2018-04-05T13:22:14Z"
   },
   { // Another order
   }
]

A returned order representation contains the results of the two order processing steps (paymentStatus and provisioningStatus) and the status of the order.

Get Filtered Orders

To select the list of orders by some criteria, the listOrders operation provides custom filters similar to Resource Query Language. In this case, a request can look as follows:

GET /aps/2/services/order-manager/orders?in({property},{value}),select({linkToResources}),ge(creationDate,{fromDate}),le(creationDate,{toDate}),like(number,*000001),limit({from},{to})

The following functions can be used:

• in verifies if a property is in a specified list, for example, request only sales orders and billing orders:

  in(type,(SO,BO))
  

  The following properties are allowed in the function:

  • resellerId is APS ID of a reseller that provides the ordered services.
  • customerId is APS ID of a customer that placed the order.
  • status is an order status in accordance with the APS type specification.
  • type is an order type as specified by the OrderRequest structure of the APS type.
  • orderId is an order UUID.
  • orderNumber is a string ID assigned by the platform to an order, for example, “SO000004”.
  • provisioningStatus is an order provisioning status as specified by the ProvisioningStatus enum.
  • paymentStatus is the payment status of an order as specified by the PaymentStatus enum.

• like verifies if a property matches a wildcard mask that uses the wildcard symbols * and ?. Currently, the function is applicable to the orderNumber property only, for example:

  like(number,*00001)
  

• select requires details about a linked resource. Currently, the only link that can be specified is subscription, that is select(subscription).

• ge and le (respectively “Greater or Equal” and “Lower or Equal”) functions are applicable to the data-time properties to select the orders in a certain date-time interval, for example, request orders created between the specified data-time:

  ge(creationTime,2018-04-26T16:00:00Z),le(creationTime,2018-04-26T18:00:00Z)
  

• limit fetches orders in a range of numbers, for example get orders in the range from 0 to 9:

  limit(0,9)
  

Get Order Details

To get the full JSON representation of an order, a request must specify the order APS ID in the URL as in the following example:

GET /aps/2/services/order-manager/orders/18131926-c152-4652-8a29-3fe076929f4b

In case of success, the response looks similar to the following:

HTTP/1.1 200 OK

{
   "orderId": "18131926-c152-4652-8a29-3fe076929f4b",
   "orderNumber": "SO000001",
   "type": "SO",
   "status": "COMPLETED",
   "subscriptions": [
      "4c867c87-fbf7-49e8-9f7e-0d06e8f7a003"
   ]
}

From the response, the external management system will get the following data that it can subject to further processing:

• APS ID of the order.
• The order status that can be one of: “NOT_STARTED”, “IN_PROGRESS”, “PROBLEM”, “CANCELED”, or “COMPLETED”.
• The order number generated by the platform internally. This attribute allows a staff member to find an order in the user panel.
• A list of subscriptions (APS IDs) the order is bound to.

Estimate Order Price

The estimateOrder custom operation calculates the price details for an arbitrary sales order without the order creation. Typically, resellers use it to estimate the price for a customer whose APS ID must be in the request.

The following examples are based on the provider-reseller-customer chain:

The configuration of such a sales scheme is similar to the one described in the concepts. In addition, it requires the configuration of discounts and taxes that we suppose is already done.

The estimation operation takes into account the discounts, promos, and taxes valid for a specified customer. It is possible to exclude tax calculation by adding the includeTaxes=false input query parameter.

POST /aps/2/services/order-manager/orders/estimate

{
   "type": "SALES",
   "accountId" : "00b60056-8b0a-4981-8ca4-d114346cd652",
   "promoCode" : "123",
   "products" : [{
      "planId" : "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
      "period" : {
         "unit" : "MONTHS",
         "duration" : 1
      },
      "resources" : [{
         "resourceId" : "2f8905f8-4302-49d7-ab7f-65c9036addf0",
         "amount" : 20
      }]
   }]
}

Note

Refer to the Set Special Prices section for details about special prices.

A response looks like this:

HTTP/1.1 200 OK

{
   "promoResult": "APPLIED",
   "total": 20.839999999999996,
   "subTotal": 18.939999999999998,
   "taxTotal": 1.9,
   "exclusiveTaxTotal": 1.9,
   "details": [
      {
         "type": "PLAN_SETUP",
         "planId": "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
         "period": {
            "unit": "MONTHS",
            "duration": 1
         },
         "description": "Cloud VPSes Setup",
         "quantity": 1.0,
         "lowerBound": 0.0,
         "unitOfMeasure": "item",
         "unitPrice": 2.0,
         "extendedPrice": 1.5,
         "discount": {
            "type": "PERCENT",
            "value": 25.0,
            "amount": 0.5
         },
         "taxAmount": 0.15,
         "exclusiveTaxAmount": 0.15
      },
      {
         "type": "PLAN_RECURRING",
         "planId": "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
         "period": {
            "unit": "MONTHS",
            "duration": 1
         },
         "duration": {
            "unit": "MONTHS",
            "duration": 1.0
         },
         "description": "Cloud VPSes Recurring",
         "quantity": 1.0,
         "lowerBound": 0.0,
         "unitOfMeasure": "item",
         "unitPrice": 4.25,
         "extendedPrice": 3.19,
         "discount": {
            "type": "PERCENT",
            "value": 25.0,
            "amount": 1.06
         },
         "taxAmount": 0.32,
         "exclusiveTaxAmount": 0.32
      },
      {
         "type": "RESOURCE_RECURRING",
         "planId": "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
         "period": {
            "unit": "MONTHS",
            "duration": 1
         },
         "resourceId": "2f8905f8-4302-49d7-ab7f-65c9036addf0",
         "duration": {
            "unit": "MONTHS",
            "duration": 1.0
         },
         "description": "null Recurring",
         "quantity": 19.0,
         "lowerBound": 0.0,
         "unitOfMeasure": "unit",
         "unitPrice": 1.0,
         "extendedPrice": 14.25,
         "discount": {
            "type": "PERCENT",
            "value": 25.0,
            "amount": 4.75
         },
         "taxAmount": 1.43,
         "exclusiveTaxAmount": 1.43
      }
   ]
}

Note

1. There are two types of taxes, those that are included in the initial price (inclusive taxes) and those that are added to the initial price (exclusive taxes).

2. In the response, the total estimated price total is the sum of subtotal and exclusiveTaxTotal.

Set Special Prices

Special Pricing Mechanism

When calling a custom operation that creates a Sales Order or estimates an order as described in the Estimate Order Price section, it is possible to add the specialPricing structure inside the main input OrderRequest structure. The added structure is applicable to a list of specified order types and it redefines some spot prices of the service plans specified in those order types:

"specialPricing" : {
   "applicableTo" : [ /* One or more "SALES", "RENEWAL", or "SWITCH_PLAN" strings */ ],
   "products" : [ /* One or more service plans with redefined prices and costs */ ]
}

If at least one special price is applicable to a subscription, the final prices in that subscription are adjusted by creating automatically a promo bound to the subscription. Unlike other promos, such a special promo is not included in the marketing configuration (Products > Marketing) and it is applicable only to its bound subscription.

For example, when creating a sales order with special prices applicable to all three order types, the auto-generated new promo will influence not only the price of the new subscription but also all subsequent renewal orders and a change order (when switching the subscription).

An entry in the products list is a service plan with the new (redefined) spot prices and costs. The general format of an entry is:

{
   "planId": "<UUID>",
   "period": {
       "unit": "<string>", // DAYS | MONTHS | YEARS
       "duration": "<int>",
   },
   "prices": {
       "setup": "<number>",
       "recurring": "<number>",
       "renewal": "<number>",
       "transfer": "<number>"
   },
   "costs": {
       "setup": "<number>",
       "recurring": "<number>",
       "renewal": "<number>",
       "transfer": "<number>"
   }
   "resources": [
       {
           "resourceId": "<UUID>",
           "prices": {
               "setup": "<number>",
               "recurring": "<number>",
               "overuse": "<number>"
           },
           "costs": {
               "setup": "<number>",
               "recurring": "<number>",
               "overuse": "<number>"
           }
       },
       // ... more resource rates
   ]
}

The cost is the price that a reseller pays to its parent for a delegated service plan. For example, an L1 reseller delegates a service plan to an L2 reseller and gives 10% discount for every spot price in that service plan. So, if a subscription price for a customer of the L2 reseller is $100 it will cost $90 for the L2 reseller.

Note

With the above definition in mind, the cost of a service plan for a reseller (for example, an L2 reseller) can be changed only by the reseller’s parent (L1 reseller or the provider).

In the following example, the provider delegates a service plan to a reseller that will sell that service plan to its customers as presented in the Estimate Order Price section. The provider sends an estimation request for a sales order containing special prices for the customer and special costs for the reseller:

POST /aps/2/services/order-manager/orders/estimate

{
   "type": "SALES",
   "accountId" : "00b60056-8b0a-4981-8ca4-d114346cd652",
   "promoCode" : "123",
   "products" : [{
      "planId" : "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
      "period" : {
         "unit" : "MONTHS",
         "duration" : 1
      },
      "resources" : [{
         "resourceId" : "2f8905f8-4302-49d7-ab7f-65c9036addf0",
         "amount" : 20
      }]
   }],
   "specialPricing": {
      "applicableTo" : [ "SALES", "RENEWAL", "SWITCH_PLAN" ],
      "products": [
         {
            "planId": "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
            "period": {
               "unit": "MONTHS",
               "duration": 1
            },
            "prices": {
               "setup": 1.2
            },
            "costs": {
               "setup": 1.0,
               "recurring": 14.0
            },
            "resources": [
               {
                  "resourceId": "2f8905f8-4302-49d7-ab7f-65c9036addf0",
                  "prices": {
                     "recurring": 0.5
                  },
                  "costs": {
                     "recurring": 0.3                                }
               }
            ]
         }
      ]
   }
}

The response looks as follows:

HTTP/1.1 200 OK

{
   "promoResult": "APPLIED",
   "total": 16.45,
   "subTotal": 14.95,
   "taxTotal": 1.5,
   "exclusiveTaxTotal": 1.5,
   "details": [
      {
         "type": "PLAN_SETUP",
         "planId": "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
         "period": {
            "unit": "MONTHS",
            "duration": 1
         },
         "description": "Cloud VPSes Setup",
         "quantity": 1.0,
         "lowerBound": 0.0,
         "unitOfMeasure": "item",
         "unitPrice": 1.2,
         "extendedPrice": 1.2,
         "discount": {
            "type": "FIXED",
            "value": 1.2,
            "amount": 0.8
         },
         "taxAmount": 0.12,
         "exclusiveTaxAmount": 0.12
      },
      {
         "type": "PLAN_RECURRING",
         "planId": "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
         "period": {
            "unit": "MONTHS",
            "duration": 1
         },
         "duration": {
            "unit": "MONTHS",
            "duration": 1.0
         },
         "description": "Cloud VPSes Recurring",
         "quantity": 1.0,
         "lowerBound": 0.0,
         "unitOfMeasure": "item",
         "unitPrice": 4.25,
         "extendedPrice": 4.25,
         "taxAmount": 0.43,
         "exclusiveTaxAmount": 0.43
      },
      {
         "type": "RESOURCE_RECURRING",
         "planId": "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
         "period": {
            "unit": "MONTHS",
            "duration": 1
         },
         "resourceId": "2f8905f8-4302-49d7-ab7f-65c9036addf0",
         "duration": {
            "unit": "MONTHS",
            "duration": 1.0
         },
         "description": "null Recurring",
         "quantity": 19.0,
         "lowerBound": 0.0,
         "unitOfMeasure": "unit",
         "unitPrice": 0.5,
         "extendedPrice": 9.5,
         "discount": {
            "type": "FIXED",
            "value": 0.5,
            "amount": 9.5
         },
         "taxAmount": 0.95,
         "exclusiveTaxAmount": 0.95
      }
   ]
}

Once the order estimation satisfies the requesting system, the latter can place a sales order with the same configuration, that is:

POST /aps/2/services/order-manager/orders

{
   "type": "SALES",
   "accountId" : "00b60056-8b0a-4981-8ca4-d114346cd652",
   "promoCode" : "123",
   "products" : [{
      "planId" : "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
      "period" : {
         "unit" : "MONTHS",
         "duration" : 1
      },
      "resources" : [{
         "resourceId" : "2f8905f8-4302-49d7-ab7f-65c9036addf0",
         "amount" : 20
      }]
   }],
   "specialPricing": {
      "applicableTo" : [ "SALES", "RENEWAL", "SWITCH_PLAN" ],
      "products": [
         {
            "planId": "6b64da9a-f8e6-4cbd-8aef-de304a27b627",
            "period": {
               "unit": "MONTHS",
               "duration": 1
            },
            "prices": {
               "setup": 1.2
            },
            "costs": {
               "setup": 1.0,
               "recurring": 14.0
            },
            "resources": [
               {
                  "resourceId": "2f8905f8-4302-49d7-ab7f-65c9036addf0",
                  "prices": {
                     "recurring": 0.5
                  },
                  "costs": {
                     "recurring": 0.3                                }
               }
            ]
         }
      ]
   }
}

As usually, the response must contain the ID of the created order. On completion of the order processing, you can find the new customer subscription with a special promo attached to it:

Limitation

The special pricing works only when creating or estimating a Sales Order.

← Manage Users

Manage Subscriptions →