SKUManagement¶

Synthetic resource for operations with SKU

In this document:

Schema
Custom Operations
Structures
Examples

Schema ¶

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

{
  "name": "SKUManagement",
  "id": "http://www.odin.com/oa/billing/sku/dispatcher/1.0",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "operations": {
    "ratesList": {
      "path": "/vendor/{vendorUuid}/rates",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "SKU"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "vendorUuid": {
          "kind": "path",
          "type": "string"
        },
        "appId": {
          "kind": "query",
          "type": "string"
        },
        "planApsId": {
          "kind": "query",
          "type": "string"
        }
      }
    },
    "updateRates": {
      "path": "/vendor/{vendorUuid}/rates",
      "verb": "PUT",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "vendorUuid": {
          "kind": "path",
          "type": "string"
        },
        "skuList": {
          "kind": "body",
          "type": "array",
          "required": true
        }
      }
    },
    "synchronize": {
      "path": "/vendor/{vendorUuid}/synchronize",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "vendorUuid": {
          "kind": "path",
          "type": "string"
        }
      }
    }
  },
  "structures": {
    "Currency": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string"
        },
        "code": {
          "type": "string"
        }
      }
    },
    "SKU": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "feeTypes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "price": {
          "type": "Currency"
        },
        "msrp": {
          "type": "Currency"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "http://aps-standard.org/types/core/i18n/1.3#MLString"
        },
        "plans": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}

The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:

POST  /aps/2/services/sku-manager/<operation-path>?<query-params>

{/*<body params>*/}

In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.

Custom Operations ¶

OPERATION	VERB	PATH	RETURNS	Description
ratesList	GET	/vendor/{vendorUuid}/rates	List of SKUs for specified vendor.	Get SKU Rates by Application.
updateRates	PUT	/vendor/{vendorUuid}/rates		Update SKU Rates
synchronize	POST	/vendor/{vendorUuid}/synchronize		Asynchronous call on synchronization of delegated plans to all sub-resellers. The operation is DEPRECATED The “synchronize” operation requires the APS ID of a reseller whose service plans it must synchronize. The process updates the service plans delegated to the specified reseller from its vendor and then it updates the service plans delegated by the specified reseller to all its downstream sub-resellers. Warning: All prices will be updated, including ones in ‘Manage by Myself’ plans.

ratesList¶

HTTP Request

GET /aps/2/services/sku-manager/vendor/{vendorUuid}/rates

Description

Get SKU Rates by Application.

Parameters

PARAMETER	TYPE	DESCRIPTION
vendorUuid	String
appId	String	(optional) Identifier of APS application (URI string see Application ID)
planApsId	String	(Optional) UUID of specified Service Plan for filtering result

Returns

List of SKUs for specified vendor.

updateRates¶

HTTP Request

PUT /aps/2/services/sku-manager/vendor/{vendorUuid}/rates

Description

Update SKU Rates

Parameters

PARAMETER	TYPE	DESCRIPTION
vendorUuid	String
skuList	Array	SKUs that should be updated

Returns

synchronize¶

HTTP Request

POST /aps/2/services/sku-manager/vendor/{vendorUuid}/synchronize

Description

Asynchronous call on synchronization of delegated plans to all sub-resellers. The operation is DEPRECATED The “synchronize” operation requires the APS ID of a reseller whose service plans it must synchronize. The process updates the service plans delegated to the specified reseller from its vendor and then it updates the service plans delegated by the specified reseller to all its downstream sub-resellers. Warning: All prices will be updated, including ones in ‘Manage by Myself’ plans.

Parameters

PARAMETER	TYPE	DESCRIPTION
vendorUuid	String

Returns

Structures ¶

Currency¶

Basic currency structure.

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

SKU¶

SKU Rates structure

NAME	TYPE	ATTRIBUTES	DESCRIPTION
id	Integer	Not Required	Identifier of SKU
feeTypes	Array of String	Not Required	List of fee types, that SKU created for
price	Currency	Not Required	Price of SKU
msrp	Currency	Not Required	Manufacturer’s Suggested Retail Price of SKU
name	String	Not Required	SKU name
description	I18n	Not Required	SKU description
plans	Array of String	Not Required	List of plans identifiers which include this SKU
resources	Array of String	Not Required	List of BSS resources that participates in this SKU

Examples ¶

Get List of SKUs¶

Use the rateList operation to get the list of SKUs with the assigned fees:

GET /aps/2/services/sku-manager/vendor/0ab950d1-abc9-4433-a87d-8ba009bf4bce/rates

The response contains a list of all SKUs with the assigned fees. The following example shows only two SKU structures for demo:

HTTP/1.1 200 OK

[
   {
      "id": 2,
      "feeTypes": [
         "RECURRING"
      ],
      "price": {
         "value": "4.25",
         "code": "USD"
      },
      "msrp": {/* ... */},
      "name": "user-management-1month-recurring",
      "description": {
         "en_US": "Demo cloud VPS and User Management service - 1 month recurring fee."
      },
      "plans": [
         "4"
      ]
   },
   {
      "id": 5,
      "feeTypes": [
         "RECURRING"
      ],
      "price": {
         "value": "1.5",
         "code": "USD"
      },
      "msrp": {/* ... */},
      "name": "user-management-resource-PremiumProfile-recurring",
      "description": {/* ... */},
      "plans": [
         "4"
      ],
      "resources": [
         "1000107"
      ]
   },
   /* ... */
]

The following response excerpt shows two SKU structures with the same ID bound to the setup fee in two different plans (plan #4 and plan #5):

[
   {
      "id": 2,
      "feeTypes": [
         "RECURRING"
      ],
      "price": {
         "value": "4.25",
         "code": "USD"
      },
      "msrp": { /* ... */ },
      "name": "user-management-1month-recurring",
      "description": {
         "en_US": "Demo cloud VPS and User Management service - 1 month recurring fee."
      },
      "plans": [
         "4"
      ]
   },
   {
      "id": 2,
      "feeTypes": [
         "RECURRING"
      ],
      "price": {
         "value": "0.0",
         "code": "USD"
      },
      "msrp": { /* ... */ },
      "name": "user-management-1month-recurring",
      "description": {
         "en_US": "Demo cloud VPS and User Management service - 1 month recurring fee."
      },
      "plans": [
         "5"
      ]
   },
   /* ... */
]

Get SKUs by Application¶

The SKU API allows getting a list of SKUs assigned to those fees that participate in selling services of a particular application. This is possible by adding a custom filter id={AppId}, where {AppId} is the APS ID assigned to the application in its APP-META.xml file. For example:

GET /aps/2/services/sku-manager/vendor/0ab950d1-abc9-4433-a87d-8ba009bf4bce/rates?appId=http://aps-standard.org/samples/bss-starter

Update Specified Fees¶

The following request for update sends the new values to all fees assigned to the SKUs whose IDs are specified in the request body:

PUT /aps/2/services/sku-manager/vendor/0ab950d1-abc9-4433-a87d-8ba009bf4bce/rates

[
   {
      "id": 2,
      "price": {
         "value": "4.25",
         "code": "USD"
      },
      "msrp": {
         "value": "4.25",
         "code": "USD"
      }
   },
   {
      "id": 5,
      "price": {
         "value": "1.5",
         "code": "USD"
      },
      "msrp": {
         "value": "1.5",
         "code": "USD"
      }
   }
]

In case of success, the response is:

HTTP/1.1 200 OK

Verify Updates¶

To verify the result, use the same read operation as in the previous Get Fees step:

GET /aps/2/services/sku-manager/vendor/0ab950d1-abc9-4433-a87d-8ba009bf4bce/rates

In the response, the updated structures must look as follows:

HTTP/1.1 200 OK

[
   {
      "id": 2,
      "feeTypes": [
         "RECURRING"
      ],
      "price": {
         "value": "4.25",
         "code": "USD"
      },
      "msrp": {
         "value": "4.25",
         "code": "USD"
      },
      "name": "user-management-1month-recurring",
      "description": { /* ... */ },
      "plans": [
         "4",
         "5"
      ]
   },
   {
      "id": 5,
      "feeTypes": [
         "RECURRING"
      ],
      "price": {
         "value": "1.5",
         "code": "USD"
      },
      "msrp": {
         "value": "1.5",
         "code": "USD"
      },
      "name": "user-management-resource-PremiumProfile-recurring",
      "description": { /* ... */ },
      "plans": [
         "4",
         "5"
      ],
      "resources": [
         "1000112",
         "1000107"
      ]
   },

]

Update and Synchronize Fees¶

Any time the management system needs to update the fees throughout the sales channels, it can first update the prices at the highest level using the updateRates operation and then sync the fees by calling the synchronize operation.

Update the prices:

PUT /aps/2/services/sku-manager/vendor/0ab950d1-abc9-4433-a87d-8ba009bf4bce/rates

[ {<SKU-1>}, ... {<SKU-N>} ]

Sync the updates with resellers:

POST /aps/2/services/sku-manager/vendor/0ab950d1-abc9-4433-a87d-8ba009bf4bce/synchronize

On completion of the last operation, the updated fees will be synced throughout the sales channels of the specified vendor.

← ProductInventory

ServicePlan →

CloudBlue Commerce API

Previous topic

Next topic

SKUManagement¶

Schema ¶

Custom Operations ¶

ratesList¶

updateRates¶

synchronize¶

Structures ¶

Currency¶

SKU¶

Examples ¶

Get List of SKUs¶

Get SKUs by Application¶

Update Specified Fees¶

Verify Updates¶

Update and Synchronize Fees¶

CloudBlue Commerce API

Previous topic

Next topic

SKUManagement¶

Schema¶

Custom Operations¶

ratesList¶

updateRates¶

synchronize¶

Structures¶

Currency¶

SKU¶

Examples¶

Get List of SKUs¶

Get SKUs by Application¶

Update Specified Fees¶

Verify Updates¶

Update and Synchronize Fees¶

Schema ¶

Custom Operations ¶

Structures ¶

Examples ¶