CloudBlue Commerce API (DRAFT)
Table Of Contents
OrderManagementApplication¶
In this document:
Schema¶
The considered APS type (download)
extends the Application APS type(s) and looks as follows:
{
"name": "OrderManagementApplication",
"id": "http://www.odin.com/billing/order-management/1.7",
"apsVersion": "2.0",
"implements": [
"http://aps-standard.org/types/core/application/1.0",
"http://odin.com/oa/types/approval-engine/client/1.0"
],
"access": {
"global": true
},
"operations": {
"orderInfo": {
"path": "/orders/{orderId}",
"verb": "GET",
"response": {
"type": "OrderInfo"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"orderId": {
"kind": "path",
"type": "string"
}
}
},
"listOrders": {
"path": "/orders",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "OrderInfo"
}
},
"errorResponse": {
"type": "object"
}
},
"placeOrder": {
"path": "/orders",
"verb": "POST",
"response": {
"type": "object"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"orderRequest": {
"kind": "body",
"type": "OrderRequest"
},
"estimate": {
"kind": "query",
"type": "string"
}
}
},
"estimateOrder": {
"path": "/orders/estimate",
"verb": "POST",
"response": {
"type": "OrderEstimationResult"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"orderRequest": {
"kind": "body",
"type": "OrderRequest"
},
"includeTaxes": {
"kind": "query",
"type": "boolean"
}
}
},
"estimateCosts": {
"path": "/orders/estimateCosts",
"verb": "POST",
"response": {
"type": "OrderEstimationResult"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"orderRequest": {
"kind": "body",
"type": "OrderRequest"
},
"includeTaxes": {
"kind": "query",
"type": "boolean"
}
}
},
"termsConditions": {
"path": "/orders/termsconditions",
"verb": "POST",
"response": {
"type": "array",
"items": {
"type": "TermCondition"
}
},
"errorResponse": {
"type": "object"
},
"parameters": {
"orderRequest": {
"kind": "body",
"type": "OrderRequest"
}
}
},
"pushOrder": {
"path": "/orders/{orderId}/push",
"verb": "POST",
"errorResponse": {
"type": "object"
},
"parameters": {
"orderId": {
"kind": "path",
"type": "string"
},
"orderRequest": {
"kind": "body",
"type": "PushOrderRequest"
}
}
},
"reasonCodes": {
"path": "/reasonCodes",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "ReasonCode"
}
},
"errorResponse": {
"type": "object"
},
"parameters": {
"operationType": {
"kind": "query",
"type": "OperationType"
}
}
},
"getPattern": {
"path": "/correctionReasonValidation",
"verb": "GET",
"response": {
"type": "CorrectionReasonValidationPatternInfo"
},
"errorResponse": {
"type": "object"
}
},
"getPatternWithLocale": {
"path": "/correctionReasonValidation/{locale}",
"verb": "GET",
"response": {
"type": "CorrectionReasonValidationInfo"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"locale": {
"kind": "path",
"type": "string"
}
}
},
"addReason": {
"path": "/correctionReasonValidation",
"verb": "POST",
"errorResponse": {
"type": "object"
},
"parameters": {
"newReasonRequest": {
"kind": "body",
"type": "CorrectionReasonValidationRequest"
}
}
},
"updateReason": {
"path": "/correctionReasonValidation",
"verb": "PUT",
"errorResponse": {
"type": "object"
},
"parameters": {
"updateReasonRequest": {
"kind": "body",
"type": "CorrectionReasonValidationRequest"
}
}
},
"deleteInvalidMessage": {
"path": "/correctionReasonValidation/{locale}",
"verb": "DELETE",
"errorResponse": {
"type": "object"
},
"parameters": {
"locale": {
"kind": "path",
"type": "string"
}
}
},
"deletePattern": {
"path": "/correctionReasonValidation",
"verb": "DELETE",
"errorResponse": {
"type": "object"
}
},
"getActions": {
"path": "/actions",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "ModuleAction"
}
},
"errorResponse": {
"type": "object"
}
},
"processApprovalResponse": {
"path": "/approvalResponse",
"verb": "POST",
"errorResponse": {
"type": "object"
}
}
},
"structures": {
"Currency": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "Currency amount"
},
"code": {
"type": "string",
"description": "Currency ISO code"
}
}
},
"OrderStatus": {
"type": "object"
},
"PaymentStatus": {
"type": "object"
},
"ProvisioningStatus": {
"type": "object"
},
"Attribute": {
"type": "object",
"properties": {
"attributeID": {
"type": "string",
"required": true
},
"value": {
"type": "string",
"required": true
}
}
},
"OrderDetailInfo": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of the order detail",
"enum": [
"UNKNOWN",
"PLAN_SETUP",
"PLAN_SETUP_REFUND",
"PLAN_SWITCH_PLAN",
"PLAN_RENEW",
"PLAN_RENEW_REFUND",
"PLAN_TRANSFER",
"PLAN_TRANSFER_REFUND",
"PLAN_RECURRING",
"PLAN_RECURRING_REFUND",
"RESOURCE_SETUP",
"RESOURCE_SETUP_REFUND",
"RESOURCE_SWITCH",
"RESOURCE_RECURRING",
"RESOURCE_RECURRING_REFUND",
"RESOURCE_OVERUSE",
"RESOURCE_DOWNGRADE",
"DISCOUNT",
"ADJUSTMENT",
"CANCELLATION",
"HANDLING_FEE",
"NON_PROVISIONING_ITEM",
"PAYMENT",
"REFUND",
"REFUND_ADJ",
"BILL_PENALTY",
"BILL_RECORD",
"RESEL_PMNT",
"DEPOSIT"
]
},
"planId": {
"type": "string",
"description": "APS ID of the service plan"
},
"period": {
"type": "Period",
"description": "Subscription period of the service plan"
},
"resourceId": {
"type": "string",
"description": "APS ID of the resource if the order detail is bound with a resource or null otherwise"
},
"bssSubscriptionId": {
"type": "string",
"description": "BSS subscription UUID"
},
"orderItemId": {
"type": "integer",
"description": "Id of order item"
},
"duration": {
"type": "Duration",
"description": "Duration of the order detail the price is calculated for."
},
"description": {
"type": "string",
"description": "Localized description of the order detail."
},
"quantity": {
"type": "number",
"description": "Quantity of the ordered resources."
},
"lowerBound": {
"type": "number",
"description": "In a case when the Tiered or Volume pricing model is used, this is the lower limit of a tier."
},
"unitOfMeasure": {
"type": "string",
"description": "Unit of resource measurement if the oder detail is bound to a resource. In all other case, the unit is \u0027item\u0027."
},
"unitPrice": {
"type": "Currency",
"description": "Price per unit."
},
"extendedPrice": {
"type": "Currency",
"description": "Total of the order detail calculated as unitPrice multiplied by quantity and multiplied by the duration."
},
"discount": {
"type": "DiscountInfo",
"description": "Applied discount; can be null."
},
"taxAmount": {
"type": "Currency",
"description": "Calculated tax containing those taxes that are included in the initial price (inclusive taxes) and those that will be added to the initial price (exclusive taxes)."
},
"exclusiveTaxAmount": {
"type": "Currency",
"description": "Exclusive tax that will be added to the initial price."
}
}
},
"OrderDetailType": {
"type": "object"
},
"Period": {
"type": "object",
"properties": {
"unit": {
"type": "string",
"description": "Subscription period unit",
"required": true,
"enum": [
"DAYS",
"MONTHS",
"YEARS"
]
},
"duration": {
"type": "integer",
"description": "Duration of subscription period",
"required": true
}
}
},
"PeriodUnit": {
"type": "object"
},
"Duration": {
"type": "object",
"properties": {
"unit": {
"type": "string",
"description": "Period unit",
"required": true,
"enum": [
"DAYS",
"MONTHS",
"YEARS"
]
},
"duration": {
"type": "number",
"description": "Duration of a period",
"required": true
}
}
},
"DiscountInfo": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Specifies if the discount is a fixed sum or percent of the initial price",
"enum": [
"PERCENT, FIXED"
]
},
"value": {
"type": "number",
"description": "Discount value, either a fixed sum or percent of the initial price"
},
"amount": {
"type": "number",
"description": "Difference between the initial price and the discounted price"
}
}
},
"DiscountType": {
"type": "object"
},
"AccountType": {
"type": "object"
},
"RelatedOrder": {
"type": "object",
"properties": {
"internalId": {
"type": "integer"
},
"buyerId": {
"type": "string"
},
"total": {
"type": "Currency"
},
"details": {
"type": "array",
"items": {
"type": "RelatedOrderDetail"
}
}
}
},
"RelatedOrderDetail": {
"type": "object",
"properties": {
"internalId": {
"type": "integer"
},
"orderItemId": {
"type": "integer"
},
"type": {
"type": "string",
"description": "Type of the order detail",
"enum": [
"UNKNOWN",
"PLAN_SETUP",
"PLAN_SETUP_REFUND",
"PLAN_SWITCH_PLAN",
"PLAN_RENEW",
"PLAN_RENEW_REFUND",
"PLAN_TRANSFER",
"PLAN_TRANSFER_REFUND",
"PLAN_RECURRING",
"PLAN_RECURRING_REFUND",
"RESOURCE_SETUP",
"RESOURCE_SETUP_REFUND",
"RESOURCE_SWITCH",
"RESOURCE_RECURRING",
"RESOURCE_RECURRING_REFUND",
"RESOURCE_OVERUSE",
"RESOURCE_DOWNGRADE",
"DISCOUNT",
"ADJUSTMENT",
"CANCELLATION",
"HANDLING_FEE",
"NON_PROVISIONING_ITEM",
"PAYMENT",
"REFUND",
"REFUND_ADJ",
"BILL_PENALTY",
"BILL_RECORD",
"RESEL_PMNT",
"DEPOSIT"
]
},
"bssSubscriptionId": {
"type": "string"
},
"resourceId": {
"type": "string"
},
"quantity": {
"type": "number"
},
"unitOfMeasure": {
"type": "string"
},
"lowerBound": {
"type": "number"
},
"discount": {
"type": "DiscountInfo"
},
"unitPrice": {
"type": "Currency"
},
"extendedPrice": {
"type": "Currency"
},
"taxAmount": {
"type": "Currency"
},
"exclusiveTaxAmount": {
"type": "Currency"
}
}
},
"OrderInfo": {
"type": "object",
"properties": {
"orderId": {
"type": "string"
},
"internalId": {
"type": "integer"
},
"orderNumber": {
"type": "string"
},
"type": {
"type": "string"
},
"total": {
"type": "Currency"
},
"taxTotal": {
"type": "Currency"
},
"exclusiveTaxTotal": {
"type": "Currency"
},
"subTotal": {
"type": "Currency"
},
"status": {
"type": "string",
"enum": [
"NOT_STARTED",
"IN_PROGRESS",
"PROBLEM",
"CANCELED",
"COMPLETED"
]
},
"bssSubscriptions": {
"type": "array",
"items": {
"type": "string"
}
},
"paymentStatus": {
"type": "string",
"enum": [
"REQUIRED",
"PROCESSING",
"PROBLEM",
"AVAILABLE",
"CANCELED",
"FINISHED"
]
},
"provisioningStatus": {
"type": "string",
"enum": [
"NOT_STARTED",
"IN_PROGRESS",
"PROBLEM",
"CANCELED",
"COMPLETED"
]
},
"ofStatus": {
"type": "string"
},
"sellerId": {
"type": "string"
},
"buyerId": {
"type": "string"
},
"orderDate": {
"type": "string",
"format": "date"
},
"expirationDate": {
"type": "string",
"format": "date"
},
"creationTime": {
"type": "string",
"format": "date"
},
"orderAttributes": {
"type": "array",
"items": {
"type": "Attribute"
}
},
"endCustomerAttributes": {
"type": "array",
"items": {
"type": "Attribute"
}
},
"details": {
"type": "array",
"items": {
"type": "OrderDetailInfo"
}
},
"endCustomerName": {
"type": "string"
},
"endCustomerType": {
"type": "string",
"enum": [
"PROVIDER",
"RESELLER",
"CUSTOMER"
]
},
"relatedOrders": {
"type": "array",
"items": {
"type": "RelatedOrder"
}
}
}
},
"OrderType": {
"type": "object"
},
"OrderRequest": {
"type": "object",
"properties": {
"type": {
"type": "OrderType",
"enum": [
"SALES",
"RENEWAL",
"CANCELLATION",
"CHANGE",
"CORRECTING"
]
}
}
},
"PromoResult": {
"type": "object"
},
"OrderDetailDTO": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of the order detail, see {@link OrderDetailType}",
"enum": [
"PLAN_SETUP",
"PLAN_RECURRING",
"PLAN_TRANSFER",
"RESOURCE_SETUP",
"RESOURCE_RECURRING",
"DISCOUNT",
"DEPOSIT"
]
},
"planId": {
"type": "string",
"description": "APS ID of the service plan"
},
"period": {
"type": "Period",
"description": "Subscription period of the service plan"
},
"resourceId": {
"type": "string",
"description": "APS ID of the resource if the order detail is bound with a resource or null otherwise"
},
"sku": {
"type": "string",
"description": "SKU"
},
"duration": {
"type": "Duration",
"description": "Duration of the order detail the price is calculated for"
},
"description": {
"type": "string",
"description": "Localized description of the order detail"
},
"quantity": {
"type": "number",
"description": "Quantity of the ordered resources"
},
"lowerBound": {
"type": "number",
"description": "In a case when the Tiered or Volume pricing model is used, this is the lower limit of a tier"
},
"unitOfMeasure": {
"type": "string",
"description": "Unit of resource measurement if the oder detail is bound to a resource. In all other case, the unit is \u0027item\u0027"
},
"unitPrice": {
"type": "Currency",
"description": "Price per unit"
},
"extendedPrice": {
"type": "Currency",
"description": "Total of the order detail calculated as unitPrice multiplied by quantity and multiplied by the duration"
},
"discount": {
"type": "DiscountReport",
"description": "Report on the applied discount; can be null"
},
"taxAmount": {
"type": "Currency",
"description": "Calculated tax containing those taxes that are included in the initial price (inclusive taxes) and those that will be added to the initial price (exclusive taxes)"
},
"exclusiveTaxAmount": {
"type": "Currency",
"description": "Exclusive tax that will be added to the initial price"
},
"taxCalcError": {
"type": "string",
"description": "Error message returned in a case of tax calculation failure"
}
}
},
"DiscountReport": {
"type": "object",
"properties": {
"type": {
"type": "DiscountType",
"description": "Specifies if the discount is a fixed sum or percent of the initial price",
"enum": [
"PERCENT",
"FIXED"
]
},
"value": {
"type": "number",
"description": "Discount value, either a fixed sum or percent of the initial price"
},
"amount": {
"type": "number",
"description": "Difference between the initial price and the discounted price"
}
}
},
"OrderEstimationResult": {
"type": "object",
"properties": {
"promoResult": {
"type": "PromoResult",
"description": "Indicates the result of the attempt to apply the promotion.",
"enum": [
"APPLIED",
"NOT_APPLICABLE",
"ALREADY_APPLIED",
"INVALID"
]
},
"total": {
"type": "Currency",
"description": "Estimated order total."
},
"subTotal": {
"type": "Currency",
"description": "Estimated order total without exclusive taxes."
},
"taxTotal": {
"type": "Currency",
"description": "Estimated order tax total."
},
"exclusiveTaxTotal": {
"type": "Currency",
"description": "Estimated order exclusive tax total."
},
"details": {
"type": "array",
"description": "Array of the order details.",
"items": {
"type": "OrderDetailDTO"
}
}
}
},
"TermCondition": {
"type": "object",
"properties": {
"termId": {
"type": "string"
},
"name": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
"PushOrderRequest": {
"type": "object",
"properties": {
"ofStatus": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
}
},
"MLString": {
"type": "object",
"properties": {
"ar_AE": {
"type": "string",
"description": "Arabic, Standard - United Arab Emirates"
},
"bg_BG": {
"type": "string",
"description": "Bulgarian - Bulgaria"
},
"cs_CZ": {
"type": "string",
"description": "Czech - Czech Republic"
},
"da_DK": {
"type": "string",
"description": "Danish - Denmark"
},
"de_DE": {
"type": "string",
"description": "German - Germany"
},
"el_GR": {
"type": "string",
"description": "Greek - Greece"
},
"en_US": {
"type": "string",
"description": "English - United States"
},
"es_ES": {
"type": "string",
"description": "Spanish - Spain"
},
"fr_FR": {
"type": "string",
"description": "French - France"
},
"he_IL": {
"type": "string",
"description": "Hebrew - Israel"
},
"hr_HR": {
"type": "string",
"description": "Croatian - Croatia"
},
"hu_HU": {
"type": "string",
"description": "Hungarian - Hungary"
},
"id_ID": {
"type": "string",
"description": "Indonesian - Indonesia"
},
"it_IT": {
"type": "string",
"description": "Italian - Italy"
},
"ja_JP": {
"type": "string",
"description": "Japanese - Japan"
},
"ko_KR": {
"type": "string",
"description": "Korean - Korea"
},
"kz_KZ": {
"type": "string",
"description": "Kazakh - Kazakhstan"
},
"nl_NL": {
"type": "string",
"description": "Dutch - The Netherlands"
},
"no_NO": {
"type": "string",
"description": "Norwegian - Norway"
},
"pl_PL": {
"type": "string",
"description": "Polish - Poland"
},
"pt_BR": {
"type": "string",
"description": "Portuguese - Brazil"
},
"pt_PT": {
"type": "string",
"description": "Portuguese - Portugal"
},
"ro_RO": {
"type": "string",
"description": "Romanian - Romania"
},
"ru_RU": {
"type": "string",
"description": "Russian - Russia"
},
"sv_SE": {
"type": "string",
"description": "Swedish - Sweden"
},
"th_TH": {
"type": "string",
"description": "Thai - Thailand"
},
"tr_TR": {
"type": "string",
"description": "Turkish - Turkey"
},
"zh_CN": {
"type": "string",
"description": "Chinese, Simplified - China"
},
"xx_XA": {
"type": "string",
"description": "Reserved 1"
},
"xx_XB": {
"type": "string",
"description": "Reserved 2"
},
"xx_XC": {
"type": "string",
"description": "Reserved 3"
},
"xx_XD": {
"type": "string",
"description": "Reserved 4"
},
"xx_XE": {
"type": "string",
"description": "Reserved 5"
},
"xx_XF": {
"type": "string",
"description": "Reserved 6"
},
"xx_XG": {
"type": "string",
"description": "Reserved 7"
},
"xx_XH": {
"type": "string",
"description": "Reserved 8"
},
"xx_XI": {
"type": "string",
"description": "Reserved 9"
},
"xx_XJ": {
"type": "string",
"description": "Reserved 10"
}
}
},
"OperationType": {
"type": "object"
},
"ReasonCode": {
"type": "object",
"properties": {
"reasonId": {
"type": "integer",
"description": "Reason id"
},
"description": {
"type": "http://aps-standard.org/types/core/i18n/1.0#MLString",
"description": "Reason description"
},
"operationType": {
"type": "string",
"description": "Subscription operation type",
"enum": [
"START_SERVICE",
"STOP_SERVICE",
"CANCEL_BY_CUSTOMER",
"CANCEL_BY_VENDOR",
"ACCOUNT_CANCELLATION",
"DESTROY_SERVICE",
"RENEW_SERVICE",
"RESTORE_SUBSCRIPTION",
"SWITCH_PLAN",
"AUTOMATIC_SYNCHRONIZATION",
"SWITCH_PERIOD",
"CHANGE_EXPIRATION_DATE",
"UPGRADE_DOWNGRADE_RESOURCES",
"SYNCHRONIZE_WITH_PLAN"
]
}
}
},
"CorrectionReasonValidationPatternInfo": {
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"messages": {
"type": "array",
"items": {
"type": "LocalizedCorrectionReasonMessage"
}
}
}
},
"CorrectionReasonValidationInfo": {
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"invalidMessage": {
"type": "string"
}
}
},
"CorrectionReasonValidationRequest": {
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"messages": {
"type": "array",
"items": {
"type": "LocalizedCorrectionReasonMessage"
}
}
}
},
"ModuleActionEntity": {
"type": "object",
"properties": {
"fields": {
"type": "array",
"description": "The fields of an approvable entity",
"items": {
"type": "TypedProperty"
}
}
}
},
"TypedProperty": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Internal name of the property that works as an internal ID"
},
"displayName": {
"type": "string",
"description": "Localized name displayed in the control panel when configuring a step in a workflow of the approval engine or processing a request for approval"
},
"type": {
"type": "string",
"description": "The type of the field value to be approved",
"enum": [
"number",
"currency",
"percentage",
"string"
]
},
"isArray": {
"type": "boolean",
"description": "If true, the client can send several fields with the same name and value type for approval when calling the submitForApproval operation of the approval engine",
"default": "false"
},
"isCriteria": {
"type": "boolean",
"description": "If true, the field can be used to configure an approval criteria in a workflow step.\n",
"default": "true"
}
}
},
"ModuleAction": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name assigned to an action."
},
"entity": {
"type": "ModuleActionEntity",
"description": "Approvable entity consisting of approvable fields."
}
}
}
}
}
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/order-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 |
|---|---|---|---|---|
GET |
/orders/{orderId} |
Order info result. |
Get information about order. |
|
GET |
/orders |
List of orders. |
Get list of orders.
Supported RQL operators: ge, in, le, like.
|
|
POST |
/orders |
Placed order result. |
Creates an order of a given type. |
|
POST |
/orders/estimate |
Detailed order estimation OrderEstimationResult. |
Estimates an order of a given type.
Sales, Change, Renewal and Cancellation orders are supported.
|
|
POST |
/orders/estimateCosts |
Detailed order estimation OrderEstimationResult. |
Estimates reseller’s transactions for an order of a given type.
Sales, Change, Renewal and Cancellation orders are supported.
|
|
POST |
/orders/termsconditions |
A list of Terms & Conditions. |
Get a list of Terms & Conditions that should be accepted by end-customer.
Sales, Change and Renewal orders are supported.
|
|
POST |
/orders/{orderId}/push |
HTTP Status “200 OK”. |
Push an order to a given order status. |
|
GET |
/reasonCodes |
List of reasons. |
Get subscription reason codes. |
|
GET |
/correctionReasonValidation |
A pattern for correction reason validation. |
Get information about a pattern for correction reason validation (with a validation regexp and a map of all pairs “locale -> invalidMessage”) for current vendor. |
|
GET |
/correctionReasonValidation/{locale} |
A correction reason validation for specified locale. |
Get information about correction reason validation for current vendor and specified locale. |
|
POST |
/correctionReasonValidation |
Add a correction reason validation with specified params. |
||
PUT |
/correctionReasonValidation |
Update a correction reason validation with specified params. |
||
DELETE |
/correctionReasonValidation/{locale} |
Remove an invalid message for specified locale. |
||
DELETE |
/correctionReasonValidation |
Remove a validation pattern for current vendor. |
||
GET |
/actions |
List of actions and entities. |
Get list of actions and entities these actions are performed with that require approval. |
|
POST |
/approvalResponse |
Process response from Approval Engine. |
orderInfo¶
HTTP Request
GET /aps/2/services/order-manager/orders/{orderId}
Description
Get information about order.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
orderId |
String |
Order UUID. |
Returns
Order info result.
listOrders¶
HTTP Request
GET /aps/2/services/order-manager/orders
Description
Returns
List of orders.
placeOrder¶
HTTP Request
POST /aps/2/services/order-manager/orders
Description
Creates an order of a given type.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
orderRequest |
Order request. |
|
estimate |
String |
Order estimation param. If set, order will not be created, and will be just calculated. |
Returns
Placed order result.
estimateOrder¶
HTTP Request
POST /aps/2/services/order-manager/orders/estimate
Description
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
orderRequest |
Order request. |
|
includeTaxes |
Boolean |
Boolean flag whether estimate order with taxes. |
Returns
Detailed order estimation OrderEstimationResult.
estimateCosts¶
HTTP Request
POST /aps/2/services/order-manager/orders/estimateCosts
Description
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
orderRequest |
Order request. |
|
includeTaxes |
Boolean |
Boolean flag whether estimate order with taxes. |
Returns
Detailed order estimation OrderEstimationResult.
termsConditions¶
HTTP Request
POST /aps/2/services/order-manager/orders/termsconditions
Description
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
orderRequest |
Order request. |
Returns
A list of Terms & Conditions.
pushOrder¶
HTTP Request
POST /aps/2/services/order-manager/orders/{orderId}/push
Description
Push an order to a given order status.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
orderId |
String |
Order UUID. |
orderRequest |
Order request. |
Returns
HTTP Status “200 OK”.
reasonCodes¶
HTTP Request
GET /aps/2/services/order-manager/reasonCodes
Description
Get subscription reason codes.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
operationType |
Subscription operation type, optional. |
Returns
List of reasons.
getPattern¶
HTTP Request
GET /aps/2/services/order-manager/correctionReasonValidation
Description
Get information about a pattern for correction reason validation (with a validation regexp and a map of all pairs “locale -> invalidMessage”) for current vendor.
Returns
A pattern for correction reason validation.
getPatternWithLocale¶
HTTP Request
GET /aps/2/services/order-manager/correctionReasonValidation/{locale}
Description
Get information about correction reason validation for current vendor and specified locale.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
locale |
String |
A locale. |
Returns
A correction reason validation for specified locale.
addReason¶
HTTP Request
POST /aps/2/services/order-manager/correctionReasonValidation
Description
Add a correction reason validation with specified params.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
newReasonRequest |
A request with params for new correction reason. |
Returns
updateReason¶
HTTP Request
PUT /aps/2/services/order-manager/correctionReasonValidation
Description
Update a correction reason validation with specified params.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
updateReasonRequest |
A request with params to be updated in the correction reason. |
Returns
deleteInvalidMessage¶
HTTP Request
DELETE /aps/2/services/order-manager/correctionReasonValidation/{locale}
Description
Remove an invalid message for specified locale.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
locale |
String |
Locale name. |
Returns
deletePattern¶
HTTP Request
DELETE /aps/2/services/order-manager/correctionReasonValidation
Description
Remove a validation pattern for current vendor.
Returns
getActions¶
HTTP Request
GET /aps/2/services/order-manager/actions
Description
Get list of actions and entities these actions are performed with that require approval.
Returns
List of actions and entities.
processApprovalResponse¶
HTTP Request
POST /aps/2/services/order-manager/approvalResponse
Description
Process response from Approval Engine.
Returns
Structures¶
Currency¶
Currency with ISO code and amount.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
value |
Number |
Not Required |
Currency amount. |
|
code |
String |
Not Required |
Currency ISO code. |
OrderStatus¶
NOT_STARTED - Order not started. IN_PROGRESS - Order in progress. PROBLEM - Order has problem. CANCELED - Order canceled. COMPLETED - Order completed. PaymentStatus¶
REQUIRED - Payment is required. PROCESSING - Payment is in processing. PROBLEM - There is a problem. AVAILABLE - Payment is available. CANCELED - Payment is cancelled. FINISHED - Payment is finished. ProvisioningStatus¶
NOT_STARTED - Order provisioning is not started. IN_PROGRESS - Order provisioning is in progress. PROBLEM - Order provisioning has finished with a problem. CANCELED - Order provisioning is canceled. COMPLETED - Order provisioning has completed. Attribute¶
This type represents billing attributes.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
attributeID |
String |
Required |
Identifier of the attribute. |
|
value |
String |
Required |
Value of the attribute. |
OrderDetailInfo¶
Represent detailed information of an order.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
type |
Enum |
Not Required |
Type of the order detail. See OrderDetailType.
Type of the order detail:
UNKNOWN - any order detail. PLAN_SETUP - plan setup fee. PLAN_SETUP_REFUND - plan setup Refund. PLAN_SWITCH_PLAN - plan switch. PLAN_RENEW - plan renew. PLAN_RENEW_REFUND - plan renew refund. PLAN_TRANSFER - plan transfer fee. PLAN_TRANSFER_REFUND - plan transfer refund. PLAN_RECURRING - plan recurring fee. PLAN_RECURRING_REFUND - plan recurring refund. RESOURCE_SETUP - resource setup fee. RESOURCE_SETUP_REFUND - resource setup refund. RESOURCE_SWITCH - resource switch. RESOURCE_RECURRING - resource recurring fee. RESOURCE_RECURRING_REFUND - resource recurring refund. RESOURCE_OVERUSE - resource overuse. RESOURCE_DOWNGRADE - resource downgrade. DISCOUNT - discount. ADJUSTMENT - adjustment. CANCELLATION - cancellation. HANDLING_FEE - handling fee. NON_PROVISIONING_ITEM - non provisioning item. PAYMENT - payment. REFUND - refund. REFUND_ADJ - refund adjustment. BILL_PENALTY - billing penalty. BILL_RECORD - billing record. RESEL_PMNT - reseller payment. DEPOSIT - deposit. |
|
planId |
String |
Not Required |
APS ID of the service plan. |
|
period |
Not Required |
Subscription period of the service plan. See Period. |
||
resourceId |
String |
Not Required |
APS ID of the resource if the order detail is bound with a resource or null otherwise. |
|
bssSubscriptionId |
String |
Not Required |
BSS subscription UUID. |
|
orderItemId |
Integer |
Not Required |
Id of order item. |
|
duration |
Not Required |
Duration of the order detail the price is calculated for. See Duration. |
||
description |
String |
Not Required |
Localized description of the order detail. |
|
quantity |
Number |
Not Required |
Quantity of the ordered resources. |
|
lowerBound |
Number |
Not Required |
In a case when the Tiered or Volume pricing model is used, this is the lower limit of a tier. |
|
unitOfMeasure |
String |
Not Required |
Unit of resource measurement if the oder detail is bound to a resource. In all other case, the unit is item. |
|
unitPrice |
Not Required |
Price per unit. See Currency. |
||
extendedPrice |
Not Required |
Total of the order detail calculated as unitPrice multiplied by quantity and multiplied by the duration. See Currency. |
||
discount |
Not Required |
Applied discount; can be null. See DiscountInfo. |
||
taxAmount |
Not Required |
Calculated tax containing those taxes that are included in the initial price (inclusive taxes) and those that will be added to the initial price (exclusive taxes). See Currency. |
||
exclusiveTaxAmount |
Not Required |
Exclusive tax that will be added to the initial price. See Currency. |
OrderDetailType¶
UNKNOWN - any order detail. PLAN_SETUP - plan setup fee. PLAN_SETUP_REFUND - plan setup Refund. PLAN_SWITCH_PLAN - plan switch. PLAN_RENEW - plan renew. PLAN_RENEW_REFUND - plan renew refund. PLAN_TRANSFER - plan transfer fee. PLAN_TRANSFER_REFUND - plan transfer refund. PLAN_RECURRING - plan recurring fee. PLAN_RECURRING_REFUND - plan recurring refund. RESOURCE_SETUP - resource setup fee. RESOURCE_SETUP_REFUND - resource setup refund. RESOURCE_SWITCH - resource switch. RESOURCE_RECURRING - resource recurring fee. RESOURCE_RECURRING_REFUND - resource recurring refund. RESOURCE_OVERUSE - resource overuse. RESOURCE_DOWNGRADE - resource downgrade. DISCOUNT - discount. ADJUSTMENT - adjustment. CANCELLATION - cancellation. HANDLING_FEE - handling fee. NON_PROVISIONING_ITEM - non provisioning item. PAYMENT - payment. REFUND - refund. REFUND_ADJ - refund adjustment. BILL_PENALTY - billing penalty. BILL_RECORD - billing record. RESEL_PMNT - reseller payment. DEPOSIT - deposit.Period¶
Subscription period duration and type structure.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
unit |
Enum |
Required |
Subscription period unit, see PeriodUnit. |
|
duration |
Integer |
Required |
Duration of subscription period. |
PeriodUnit¶
DAYS - Periodically on Statement Day. MONTHS - Fixed Number of Months. YEARS - Fixed Number of Years.Duration¶
Duration of a period.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
unit |
Enum |
Required |
Period unit, see PeriodUnit.
Subscription period unit type:
DAYS - Periodically on Statement Day. MONTHS - Fixed Number of Months. YEARS - Fixed Number of Years. |
|
duration |
Number |
Required |
Duration of a period. |
DiscountInfo¶
Represents the applied discount.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
type |
Enum |
Not Required |
Specifies if the discount is a fixed sum or percent of the initial price. See DiscountType.
Specifies if the discount is a fixed sum or percent of the initial price:
PERCENT - discount is a percent of the initial price. FIXED - discount is a fixed sum. |
|
value |
Number |
Not Required |
Discount value, either a fixed sum or percent of the initial price. |
|
amount |
Number |
Not Required |
Difference between the initial price and the discounted price. |
DiscountType¶
PERCENT - discount is a percent of the initial price. FIXED - discount is a fixed sum.AccountType¶
PROVIDER - Provider account. RESELLER - Reseller account. CLIENT - Customer account.OrderInfo¶
Information about order
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
orderId |
String |
Not Required |
Order identifier for APS - UUID. |
|
internalId |
Integer |
Not Required |
Order PBA integer identifier. |
|
orderNumber |
String |
Not Required |
Order number. |
|
type |
String |
Not Required |
Order type. |
|
total |
Not Required |
Order total sum. See Currency. |
||
taxTotal |
Not Required |
Order tax sum. See Currency. |
||
exclusiveTaxTotal |
Not Required |
Order sum of taxes which are excluded from price. See Currency. |
||
subTotal |
Not Required |
Order sum without all taxes: total - taxTotal. See Currency. |
||
status |
Enum |
Not Required |
Order status. See OrderStatus.
Order status type:
NOT_STARTED - Order not started. IN_PROGRESS - Order in progress. PROBLEM - Order has problem. CANCELED - Order canceled. COMPLETED - Order completed. |
|
bssSubscriptions |
Array of String |
Not Required |
BSS subscriptions identifiers list related to the order. |
|
paymentStatus |
Enum |
Not Required |
Order status of payments. See PaymentStatus.
Payment status type:
REQUIRED - Payment is required. PROCESSING - Payment is in processing. PROBLEM - There is a problem. AVAILABLE - Payment is available. CANCELED - Payment is cancelled. FINISHED - Payment is finished. |
|
provisioningStatus |
Enum |
Not Required |
Order status of provisioning. See ProvisioningStatus.
Provisioning status type:
NOT_STARTED - Order provisioning is not started. IN_PROGRESS - Order provisioning is in progress. PROBLEM - Order provisioning has finished with a problem. CANCELED - Order provisioning is canceled. COMPLETED - Order provisioning has completed. |
|
ofStatus |
String |
Not Required |
Order flow status. |
|
sellerId |
String |
Not Required |
Seller account APS oss id (UUID). |
|
buyerId |
String |
Not Required |
Buyer account APS oss id (UUID). |
|
orderDate |
String |
Not Required |
Order date. |
|
expirationDate |
String |
Not Required |
Order expiration date. |
|
creationTime |
String |
Not Required |
Order creation time. |
|
orderAttributes |
Array of Attribute |
Not Required |
Order attributes. See Attribute. |
|
endCustomerAttributes |
Array of Attribute |
Not Required |
Order customer attributes. See Attribute. |
|
details |
Array of OrderDetailInfo |
Not Required |
Order details. See OrderDetailInfo. |
|
endCustomerName |
String |
Not Required |
Name of order customer. |
|
endCustomerType |
Enum |
Not Required |
Type of order customer. See AccountType.
Account type:
PROVIDER - Provider account. RESELLER - Reseller account. CLIENT - Customer account. |
|
relatedOrders |
Array of RelatedOrder |
Not Required |
Reseller transactions |
OrderType¶
SALES - sales order. RENEWAL - renewal order. CANCELLATION - cancellation order. CHANGE - upgrade or downgrade a resource or change a service plan or plan period order. CORRECTING - correcting order.OrderRequest¶
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
type |
Not Required |
The exactly type of a given order, see OrderType. |
PromoResult¶
APPLIED - Discount/promotion is found by promo-code, and order is discounted. NOT_APPLICABLE - Discount/promotion is found by promo-code, but not applicable to a given order. ALREADY_APPLIED - The provided one-time promo-code is already applied to different order.INVALID - The provided promo-code is not valid, we were unable to find a discount/promotion using it.OrderDetailDTO¶
Order Detail information.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
type |
Enum |
Not Required |
Type of the order detail, see OrderDetailType.
Type of the order detail:
UNKNOWN - any order detail. PLAN_SETUP - plan setup fee. PLAN_SETUP_REFUND - plan setup Refund. PLAN_SWITCH_PLAN - plan switch. PLAN_RENEW - plan renew. PLAN_RENEW_REFUND - plan renew refund. PLAN_TRANSFER - plan transfer fee. PLAN_TRANSFER_REFUND - plan transfer refund. PLAN_RECURRING - plan recurring fee. PLAN_RECURRING_REFUND - plan recurring refund. RESOURCE_SETUP - resource setup fee. RESOURCE_SETUP_REFUND - resource setup refund. RESOURCE_SWITCH - resource switch. RESOURCE_RECURRING - resource recurring fee. RESOURCE_RECURRING_REFUND - resource recurring refund. RESOURCE_OVERUSE - resource overuse. RESOURCE_DOWNGRADE - resource downgrade. DISCOUNT - discount. ADJUSTMENT - adjustment. CANCELLATION - cancellation. HANDLING_FEE - handling fee. NON_PROVISIONING_ITEM - non provisioning item. PAYMENT - payment. REFUND - refund. REFUND_ADJ - refund adjustment. BILL_PENALTY - billing penalty. BILL_RECORD - billing record. RESEL_PMNT - reseller payment. DEPOSIT - deposit. |
|
planId |
String |
Not Required |
APS ID of the service plan. |
|
period |
Not Required |
Subscription period of the service plan. |
||
resourceId |
String |
Not Required |
APS ID of the resource if the order detail is bound with a resource or null otherwise. |
|
sku |
String |
Not Required |
SKU.. |
|
duration |
Not Required |
Duration of the order detail the price is calculated for. |
||
description |
String |
Not Required |
Localized description of the order detail. |
|
quantity |
Number |
Not Required |
Quantity of the ordered resources. |
|
lowerBound |
Number |
Not Required |
In a case when the Tiered or Volume pricing model is used, this is the lower limit of a tier. |
|
unitOfMeasure |
String |
Not Required |
Unit of resource measurement if the oder detail is bound to a resource. In all other case, the unit is item. |
|
unitPrice |
Not Required |
Price per unit. |
||
extendedPrice |
Not Required |
Total of the order detail calculated as unitPrice multiplied by quantity and multiplied by the duration. |
||
discount |
Not Required |
Report on the applied discount; can be null. |
||
taxAmount |
Not Required |
Calculated tax containing those taxes that are included in the initial price (inclusive taxes) and those that will be added to the initial price (exclusive taxes). |
||
exclusiveTaxAmount |
Not Required |
Exclusive tax that will be added to the initial price. |
||
taxCalcError |
String |
Not Required |
Error message returned in a case of tax calculation failure. |
DiscountReport¶
This structure contain information about discount.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
type |
Not Required |
Specifies if the discount is a fixed sum or percent of the initial price, see DiscountType. |
||
value |
Number |
Not Required |
Discount value, either a fixed sum or percent of the initial price. |
|
amount |
Number |
Not Required |
Difference between the initial price and the discounted price. |
OrderEstimationResult¶
Order estimation result.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
promoResult |
Not Required |
Indicates the result of the attempt to apply the promotion, see PromoResult. |
||
total |
Not Required |
Estimated order total. |
||
subTotal |
Not Required |
Estimated order total without exclusive taxes. |
||
taxTotal |
Not Required |
Estimated order tax total. |
||
exclusiveTaxTotal |
Not Required |
Estimated order exclusive tax total. |
||
details |
Array of OrderDetailDTO |
Not Required |
Array of the order details. |
TermCondition¶
Terms and Conditions.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
termId |
String |
Not Required |
Identifier of the condition. |
|
name |
String |
Not Required |
Name of the condition. |
|
content |
String |
Not Required |
Full text of the condition that user should accept. |
PushOrderRequest¶
Request for the order to transition to the specified status.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
ofStatus |
String |
Not Required |
Order flow status. |
MLString¶
Multi-Lang String structure
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
ar_AE |
String |
Not Required |
Arabic, Standard - United Arab Emirates. |
|
bg_BG |
String |
Not Required |
Bulgarian - Bulgaria. |
|
cs_CZ |
String |
Not Required |
Czech - Czech Republic. |
|
da_DK |
String |
Not Required |
Danish - Denmark. |
|
de_DE |
String |
Not Required |
German - Germany. |
|
el_GR |
String |
Not Required |
Greek - Greece. |
|
en_US |
String |
Not Required |
English - United States. |
|
es_ES |
String |
Not Required |
Spanish - Spain. |
|
fr_FR |
String |
Not Required |
French - France. |
|
he_IL |
String |
Not Required |
Hebrew - Israel. |
|
hr_HR |
String |
Not Required |
Croatian - Croatia. |
|
hu_HU |
String |
Not Required |
Hungarian - Hungary. |
|
id_ID |
String |
Not Required |
Indonesian - Indonesia. |
|
it_IT |
String |
Not Required |
Italian - Italy. |
|
ja_JP |
String |
Not Required |
Japanese - Japan. |
|
ko_KR |
String |
Not Required |
Korean - Korea. |
|
kz_KZ |
String |
Not Required |
Kazakh - Kazakhstan. |
|
nl_NL |
String |
Not Required |
Dutch - The Netherlands. |
|
no_NO |
String |
Not Required |
Norwegian - Norway. |
|
pl_PL |
String |
Not Required |
Polish - Poland. |
|
pt_BR |
String |
Not Required |
Portuguese - Brazil. |
|
pt_PT |
String |
Not Required |
Portuguese - Portugal. |
|
ro_RO |
String |
Not Required |
Romanian - Romania. |
|
ru_RU |
String |
Not Required |
Russian - Russia. |
|
sv_SE |
String |
Not Required |
Swedish - Sweden. |
|
th_TH |
String |
Not Required |
Thai - Thailand. |
|
tr_TR |
String |
Not Required |
Turkish - Turkey. |
|
zh_CN |
String |
Not Required |
Chinese, Simplified - China. |
|
xx_XA |
String |
Not Required |
Reserved 1. |
|
xx_XB |
String |
Not Required |
Reserved 2. |
|
xx_XC |
String |
Not Required |
Reserved 3. |
|
xx_XD |
String |
Not Required |
Reserved 4. |
|
xx_XE |
String |
Not Required |
Reserved 5. |
|
xx_XF |
String |
Not Required |
Reserved 6. |
|
xx_XG |
String |
Not Required |
Reserved 7. |
|
xx_XH |
String |
Not Required |
Reserved 8. |
|
xx_XI |
String |
Not Required |
Reserved 9. |
|
xx_XJ |
String |
Not Required |
Reserved 10. |
OperationType¶
START_SERVICE - Start Service. STOP_SERVICE - Stop Service .CANCEL_BY_CUSTOMER - Cancel by Customer. CANCEL_BY_VENDOR - Cancel by Vendor. ACCOUNT_CANCELLATION - Account Cancellation. DESTROY_SERVICE - Destroy Service. RENEW_SERVICE - Renew Service. RESTORE_SUBSCRIPTION - Restore Subscription. SWITCH_PLAN - Switch Service Plan. AUTOMATIC_SYNCHRONIZATION - Automatic Synchronization. SWITCH_PERIOD - Switch Period. CHANGE_EXPIRATION_DATE - Change Expiration Date. UPGRADE_DOWNGRADE_RESOURCES - Upgrade/Downgrade Resources. SYNCHRONIZE_WITH_PLAN - Synchronize with Plan. ReasonCode¶
Subscription Reason Code.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
reasonId |
Integer |
Not Required |
Identifier of the subscription reason. |
|
description |
Not Required |
Description of the subscription reason. |
||
operationType |
Enum |
Not Required |
OperationType of the subscription reason, see OperationType.
Subscription operation types:
START_SERVICE - Start Service. STOP_SERVICE - Stop Service .CANCEL_BY_CUSTOMER - Cancel by Customer. CANCEL_BY_VENDOR - Cancel by Vendor. ACCOUNT_CANCELLATION - Account Cancellation. DESTROY_SERVICE - Destroy Service. RENEW_SERVICE - Renew Service. RESTORE_SUBSCRIPTION - Restore Subscription. SWITCH_PLAN - Switch Service Plan. AUTOMATIC_SYNCHRONIZATION - Automatic Synchronization. SWITCH_PERIOD - Switch Period. CHANGE_EXPIRATION_DATE - Change Expiration Date. UPGRADE_DOWNGRADE_RESOURCES - Upgrade/Downgrade Resources. SYNCHRONIZE_WITH_PLAN - Synchronize with Plan. |
CorrectionReasonValidationPatternInfo¶
A correction reason validation info about a pattern (with a map of all pairs “locale -> invalidMessage”) for given vendor and language, returned by a rest endpoint.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
pattern |
String |
Not Required |
A validation pattern (a regular expression) against which a correction reason entered by a user should be validated. |
|
messages |
Array of LocalizedCorrectionReasonMessage |
Not Required |
A list of invalid messages one of which, according to user’s locale, is displayed if a user entered a correction reason which is not complies with given pattern. |
CorrectionReasonValidationInfo¶
A correction reason validation info for given vendor and language, returned by a rest endpoint.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
pattern |
String |
Not Required |
A validation pattern (a regular expression) against which a correction reason entered by a user should be validated. |
|
invalidMessage |
String |
Not Required |
An invalid message which is displayed if a user entered a correction reason which is not complies with given pattern. |
CorrectionReasonValidationRequest¶
A request for creating a correction reason validation info with given params.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
pattern |
String |
Not Required |
A validation pattern (a regular expression) against which a correction reason entered by a user should be validated. |
|
messages |
Array of LocalizedCorrectionReasonMessage |
Not Required |
A list of invalid messages with specified locales, one of which (according to user’s locale) is displayed if a user entered a correction reason which is not complies with given pattern. |
ModuleActionEntity¶
The structure combines several TypedProperty fields in a response returned by the getActions operation. It presents an approvable entity inside an approvable action.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
fields |
Array of TypedProperty |
Not Required |
The fields of an approvable entity. |
TypedProperty¶
The structure of an approvable field inside an action entity. If its isCriteria property is true, the field can be used to configure an approval criteria in a workflow step.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
name |
String |
Not Required |
Internal name of the property that works as an internal ID. |
|
displayName |
String |
Not Required |
Localized name displayed in the control panel when configuring a step in a workflow of the approval engine or processing a request for approval. |
|
type |
Enum |
Not Required |
The type of the field value to be approved. |
|
isArray |
Boolean |
Not Required |
false |
|
isCriteria |
Boolean |
Not Required |
true |
ModuleAction¶
The structure of an approvable action that is an element of an array returned by the getActions operation. The provider can configure an approval workflow for every such action.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
name |
String |
Not Required |
The name assigned to an action. |
|
entity |
Not Required |
Approvable entity consisting of approvable fields. |
Examples¶
Below, you will find the most often used operations on orders. For more demos on using the order management service by external systems, refer to Manage Orders.
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",
"internalId": 1000024,
"orderNumber": "SO000014",
"type": "SO",
"total": 308.0,
"taxTotal": 0.0,
"exclusiveTaxTotal": 0.0,
"subTotal": 308.0,
"status": "COMPLETED",
"paymentStatus": "FINISHED",
"provisioningStatus": "COMPLETED",
"ofStatus": "CP",
"sellerId": "c0d43087-da72-472a-a176-84a34608979f",
"buyerId": "d7dd06ef-20a0-41f5-b89f-768ef373ae44",
"orderDate": "2019-04-04T21:00:00Z",
"expirationDate": "2019-04-07T21:00:00Z",
"creationTime": "2019-04-05T13:22:14Z"
"orderAttributes": [],
"accountAttributes": [],
"endCustomerName": "John Smith",
"endCustomerType": "CUSTOMER"
},
{ // Another order
}
]
Get Filtered Orders¶
To select the list of orders by certain 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:
inverifies whether a property is in the specified list, for example, request only sales orders and billing orders:in(type,(SO,BO))
The following properties are allowed in the function:
resellerIdis the APS ID of a reseller that provides the ordered services.customerIdis the APS ID of a customer that placed the order.statusis an order status enum.typeis an order type as specified by theOrderRequeststructure of the APS type.orderIdis an order UUID.orderNumberis the string ID assigned by the platform to an order, for example, “SO000004”.provisioningStatusis an order provisioning status as enum.paymentStatusis the payment status of an order as enum.
likeverifies whether a property matches a wildcard mask that uses the wildcard symbols*and?. Currently, the function is applicable to theorderNumberproperty only, for example:like(number,*00001)
selectrequires details about a linked resource. Currently, the only link that can be specified issubscription, that isselect(subscription).geandle(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 the orders created between the specified data-time:ge(creationTime,2018-04-26T16:00:00Z),le(creationTime,2018-04-26T18:00:00Z)
limitfetches orders in a range of numbers, for example, fetch up to 9 orders starting from position 0: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
If successful, the response looks similar to the following:
HTTP/1.1 200 OK
{
"orderId": "18131926-c152-4652-8a29-3fe076929f4b",
"internalId": 1000002,
"orderNumber": "SO000001",
"type": "SO",
"total": {
"value": 308.0,
"code": "USD"
},
"taxTotal": {
"value": 0.0,
"code": "USD"
},
"exclusiveTaxTotal": {
"value": 0.0,
"code": "USD"
},
"subTotal": {
"value": 308.0,
"code": "USD"
},
"status": "COMPLETED",
"subscriptions": [
"4c867c87-fbf7-49e8-9f7e-0d06e8f7a003"
],
"bssSubscriptions": [
"456808a0-b5a6-4092-ab67-b77e33743a07"
],
"paymentStatus": "FINISHED",
"provisioningStatus": "COMPLETED",
"ofStatus": "CP",
"sellerId": "8265e3d7-cdf5-4acc-8ca4-267268a79aae",
"buyerId": "9d086478-d00b-40c2-86df-7bc9b862e667",
"orderDate": "2019-02-26",
"expirationDate": "2019-03-01",
"creationTime": "2019-02-26T10:01:17Z",
"orderAttributes": [],
"endCustomerAttributes": [
{
"attributeID": "external_id",
"value": "Smith-123"
}
],
"details": [
{
"type": "RESOURCE_RECURRING",
"planId": "67216414-6490-4588-bef9-7f6acf5e6a63",
"period": {
"unit": "YEARS",
"duration": 1
},
"resourceId": "6cc3ccc6-0571-4c16-8e41-3916e1136284",
"duration": {
"unit": "MONTHS",
"duration": 1.0
},
"description": "Disk Space Recurring",
"quantity": 90.0,
"lowerBound": 0.0,
"unitOfMeasure": "GB",
"unitPrice": {
"value": 1.0,
"code": "USD"
},
"extendedPrice": {
"value": 90.0,
"code": "USD"
}
"discount": {
"type": "PERCENT",
"value": 0.0,
"amount": 0.0
},
"taxAmount": {
"value": 0.0,
"code": "USD"
}
"exclusiveTaxAmount": {
"value": 0.0,
"code": "USD"
}
},
{
"type": "PLAN_RECURRING",
"planId": "67216414-6490-4588-bef9-7f6acf5e6a63",
"period": {
"unit": "YEARS",
"duration": 1
},
"duration": {
"unit": "MONTHS",
"duration": 1.0
},
"description": "VIP Maintenance and Support Recurring",
"quantity": 1.0,
"unitOfMeasure": "item",
"unitPrice": {
"value": 199.0,
"code": "USD"
}
"extendedPrice": {
"value": 199.0,
"code": "USD"
}
"discount": {
"type": "PERCENT",
"value": 0.0,
"amount": 0.0
},
"taxAmount": {
"value": 0.0,
"code": "USD"
}
"exclusiveTaxAmount": {
"value": 0.0,
"code": "USD"
}
},
{
"type": "PLAN_SETUP",
"planId": "67216414-6490-4588-bef9-7f6acf5e6a63",
"period": {
"unit": "YEARS",
"duration": 1
},
"description": "VIP Maintenance and Support Setup",
"quantity": 1.0,
"unitOfMeasure": "item",
"unitPrice": {
"value": 19.0,
"code": "USD"
}
"extendedPrice": {
"value": 19.0,
"code": "USD"
}
"discount": {
"type": "PERCENT",
"value": 0.0,
"amount": 0.0
},
"taxAmount": {
"value": 0.0,
"code": "USD"
}
"exclusiveTaxAmount": {
"value" 0.0,
"code": "USD"
}
}
],
"endCustomerName": "John Smith",
"endCustomerType": "CUSTOMER"
}
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 plans. 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": "3fef9702-b2ad-419a-9924-a56882e5f06c",
"products": [
{
"planId": "ebf17799-6a39-4133-ab9c-0afa40dcd6ae",
"period": {
"unit": "MONTHS",
"duration": 1
}
}
]
}
If there are terms and conditions bound to the requested service plans, the platform returns a list of elements containing the IDs and the contents of those terms and conditions:
[
{
"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."
}
]
Place Sales Orders¶
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" : "3fef9702-b2ad-419a-9924-a56882e5f06c",
"promoCode": "123",
"paymentMethodId": "3",
"products" : [{
"planId" : "ae0e6e84-0d37-4b17-8f6c-5709633529ab",
"period" : {
"unit" : "MONTHS",
"duration" : 1
},
"resources" : [{
"resourceId" : "1c3ab0be-3160-45a1-a9b4-7824f74673ff",
"amount" : 40
}],
"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
}
}
Place Renewal Orders¶
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": "456808a0-b5a6-4092-ab67-b77e33743a07",
"paymentMethodId": "11",
"period": {
"unit": "MONTHS",
"duration": 1
}
}
Change a Subscription Period¶
The platform allows you to switch a subscription from its current service plan to another one or to another subscription
period within the current service plan. An external management system calls the placeOrder custom
operation to start the switching process:
POST /aps/2/services/order-manager/orders
{
"type": "CHANGE",
"subscriptionId": "456808a0-b5a6-4092-ab67-b77e33743a07",
"planId": "ae0e6e84-0d37-4b17-8f6c-5709633529ab",
"paymentMethodId": "11",
"period": {
"unit": "MONTHS",
"duration": 3
}
}
Change Resource Limits¶
To buy an additional amount of resources within a subscription, an external management system calls
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",
"amount": 10
}
]
}
Cancel Subscriptions¶
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": "456808a0-b5a6-4092-ab67-b77e33743a07",
"refundType": "CREDIT_MEMO"
}
Estimate Order Fees¶
The estimation operation takes into account the discounts, promos, and taxes valid for a specified customer.
This operation will exclude the tax calculation if you add 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
}]
}]
}
The 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
}
]
}
Set Special Prices¶
In the following example, an external system sends an estimation request on behalf of the provider for a sales order containing special prices for a reseller’s 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 fulfills 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 }
}
]
}
]
}
}
The response must contain the ID of the created order.
Ordering Service Plans with Required Terms and Conditions¶
When a service plan or resource rates in it require customers to accept terms and conditions, an order for this plan will be in the IN_PROGRESS status and the provisioning process will not start until the customer accepts those terms and conditions.
In BSS, Terms and Conditions are special objects:
Depending on the Acceptance property, the Terms and Conditions are required for sales orders (if the acceptance is
for the first purchase) or for any orders (if the acceptance is for every purchase).
Terms and Conditions are bound to service plans where they are required:
When you place an order, the response will be the same as demonstrated earlier, but the order status will be IN_PROGRESS as in the following example:
{
"orderId": "611ea03e-cff7-4020-9b60-add9bde9a37f",
"internalId": 1000007,
"orderNumber": "SO000002",
"type": "SO",
"total": {
"value": 0.0,
"code": "USD"
},
"taxTotal": {
"value": 0.0,
"code": "USD"
},
"exclusiveTaxTotal": {
"value": 0.0,
"code": "USD"
},
"subTotal": {
"value": 0.0,
"code": "USD"
},
"status": "IN_PROGRESS",
"subscriptions": [],
"bssSubscriptions": [
"25e0af34-d91b-4d42-bafa-0a7bae0af919"
],
"paymentStatus": "REQUIRED",
"provisioningStatus": "NOT_STARTED",
"ofStatus": "TA",
"isEstimated": true,
"sellerId": "2a78fb85-8027-401c-896e-8e733d92c532",
"sellerInternalId": 1,
"buyerId": "598a0e22-a70a-4a6c-9dcc-9313af635108",
"buyerInternalId": 1000003,
"orderDate": "2020-07-14",
"expirationDate": "2020-07-17",
"creationTime": "2020-07-14T09:37:40Z",
"orderAttributes": [],
"endCustomerAttributes": [],
"details": [],
"orderItems": [
{
"orderItemId": 5,
"type": "CREATE",
"bssSubscriptionId": "25e0af34-d91b-4d42-bafa-0a7bae0af919",
"bssSubscriptionInternalId": 1000005,
"resources": []
}
],
"endCustomerName": "John Smith",
"endCustomerType": "CLIENT",
"relatedOrders": [],
"description": "Order for the \"SP1\" Plan for 1 Year(s). "
}
In the BSS control panel, the order looks as follows:
Limitation¶
Attributes and Parameters¶
You can use the attributes and parameters properties only when placing sales orders.
No other order types accept them.
Special Pricing¶
Limitations¶
Special pricing only works when placing or estimating sales orders. It does not work with other order types.
If special pricing is used in a request, it must contain the
applicableToproperty (even if it is an empty array).
Specifics¶
Special pricing functions similar to promotions, which is why its applicableTo property is a list
of order types similar to the one used in a promotion. For API calls, among the possible list of values (SALES, RENEWAL,
and CHANGE), the only one that affects the final prices is RENEWAL. This works as follows:
Special prices are valid for the first subscription period (until the subscription is renewed automatically or manually) regardless of the
applicableTovalue. The latter can be an empty array.When RENEWAL is specified in the the
applicableToarray, the special prices are valid for all subscription periods.
For a sales order estimation, use the empty applicableTo array, as this operation estimates only the first subscription
period.