Application Packaging Standard

Last updated 14-Nov-2018

OrderManagement

Singleton APS resource with methods for operations with orders.

Schema

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

{
  "name": "OrderManagement",
  "id": "http://www.odin.com/billing/order-management/1.4",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "access": {
    "global": true
  },
  "operations": {
    "placeOrder": {
      "path": "/orders",
      "verb": "POST",
      "response": {
        "type": "PlacedOrderResult"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "orderRequest": {
          "kind": "body",
          "type": "OrderRequest"
        },
        "estimate": {
          "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"
        }
      }
    },
    "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"
        }
      }
    },
    "orderInfo": {
      "path": "/orders/{orderId}",
      "verb": "GET",
      "response": {
        "type": "OrderInfo"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "orderId": {
          "kind": "path",
          "type": "string"
        }
      }
    },
    "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"
      }
    },
    "listOrders": {
      "path": "/orders",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "OrderInfo"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    }
  },
  "structures": {
    "PlacedOrderResult": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string"
        }
      }
    },
    "OrderRequest": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "SALES",
            "RENEWAL",
            "CANCELLATION",
            "CHANGE",
            "CORRECTING"
          ]
        }
      }
    },
    "TermCondition": {
      "type": "object",
      "properties": {
        "termId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "content": {
          "type": "string"
        }
      }
    },
    "Currency": {
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "description": "Currency amount."
        },
        "code": {
          "type": "string",
          "description": "Currency ISO code."
        }
      }
    },
    "OrderDetailDTO": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of the order detail.",
          "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."
        }
      }
    },
    "Period": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "required": true,
          "enum": [
            "DAYS",
            "MONTHS",
            "YEARS"
          ]
        },
        "duration": {
          "type": "integer",
          "required": true
        }
      }
    },
    "Duration": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "required": true,
          "enum": [
            "DAYS",
            "MONTHS",
            "YEARS"
          ]
        },
        "duration": {
          "type": "number",
          "required": true
        }
      }
    },
    "DiscountReport": {
      "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."
        }
      }
    },
    "OrderEstimationResult": {
      "type": "object",
      "properties": {
        "promoResult": {
          "type": "string",
          "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"
          }
        }
      }
    },
    "OrderStatus": {
      "type": "object"
    },
    "PaymentStatus": {
      "type": "object"
    },
    "ProvisioningStatus": {
      "type": "object"
    },
    "OrderInfo": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string"
        },
        "orderNumber": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "status": {
          "type": "OrderStatus",
          "enum": [
            "NOT_STARTED",
            "IN_PROGRESS",
            "PROBLEM",
            "CANCELED",
            "COMPLETED"
          ]
        },
        "paymentStatus": {
          "type": "PaymentStatus",
          "enum": [
            "REQUIRED",
            "PROCESSING",
            "PROBLEM",
            "AVAILABLE",
            "CANCELED",
            "FINISHED"
          ]
        },
        "provisioningStatus": {
          "type": "ProvisioningStatus",
          "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"
        }
      }
    },
    "LocalizedCorrectionReasonMessage": {
      "type": "object",
      "properties": {
        "invalidMessage": {
          "type": "string"
        },
        "locale": {
          "type": "string"
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}

Enums

NAME VALUES DESCRIPTION
OrderStatus
  • NOT_STARTED
  • IN_PROGRESS
  • PROBLEM
  • CANCELED
  • COMPLETED
Order status type.
PaymentStatus
  • REQUIRED
  • PROCESSING
  • PROBLEM
  • AVAILABLE
  • CANCELED
  • FINISHED
Payment status type.
ProvisioningStatus
  • NOT_STARTED
  • IN_PROGRESS
  • PROBLEM
  • CANCELED
  • COMPLETED
Provisioning status type.

Custom Operations

OPERATION VERB PATH RETURNS Description
addReason POST /correctionReasonValidation   Add a correction reason validation with specified params.
deleteInvalidMessage DELETE /correctionReasonValidation/{locale}   Remove an invalid message for specified locale.
deletePattern DELETE /correctionReasonValidation   Remove a validation pattern for current vendor.
estimateCosts POST /orders/estimateCosts Detailed order estimation OrderEstimationResult EXPERIMENTAL API. Estimates reseller’s transactions for an order of a given type.
estimateOrder POST /orders/estimate Detailed order estimation OrderEstimationResult EXPERIMENTAL API. Estimates an order of a given type.
getPattern 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.
getPatternWithLocale GET /correctionReasonValidation/{locale} A correction reason validation for specified locale Get information about correction reason validation for current vendor and specified locale.
listOrders GET /orders List of orders. Get list of orders. <p> Supported RQL operators: ge, in, le, like </p>
orderInfo GET /orders/{orderId} Order info result EXPERIMENTAL API. Get information about order.
placeOrder POST /orders Placed order result PlacedOrderResult EXPERIMENTAL API. Creates an order of a given type.
termsConditions POST /orders/termsconditions   Returns a list of Terms & Conditions that should be accepted by end-customer
updateReason PUT /correctionReasonValidation   Update a correction reason validation with specified params.

addReason

HTTP Request

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

Description

Add a correction reason validation with specified params.

Parameters

PARAMETER TYPE DESCRIPTION
newReasonRequest CorrectionReasonValidationRequest A request with params for new correction reason

Returns

deleteInvalidMessage

HTTP Request

DELETE /aps/2/resources/{aps-id}/correctionReasonValidation/{locale}

Description

Remove an invalid message for specified locale.

Returns

deletePattern

HTTP Request

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

Description

Remove a validation pattern for current vendor.

Returns

estimateCosts

HTTP Request

POST /aps/2/resources/{aps-id}/orders/estimateCosts

Description

EXPERIMENTAL API. Estimates reseller’s transactions for an order of a given type.

Parameters

PARAMETER TYPE DESCRIPTION
orderRequest OrderRequest Order request

Returns

Detailed order estimation OrderEstimationResult

estimateOrder

HTTP Request

POST /aps/2/resources/{aps-id}/orders/estimate

Description

EXPERIMENTAL API. Estimates an order of a given type.

Parameters

PARAMETER TYPE DESCRIPTION
orderRequest OrderRequest Order request

Returns

Detailed order estimation OrderEstimationResult

getPattern

HTTP Request

GET /aps/2/resources/{aps-id}/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/resources/{aps-id}/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

listOrders

HTTP Request

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

Description

Get list of orders. <p> Supported RQL operators: ge, in, le, like </p>

Returns

List of orders.

orderInfo

HTTP Request

GET /aps/2/resources/{aps-id}/orders/{orderId}

Description

EXPERIMENTAL API. Get information about order.

Parameters

PARAMETER TYPE DESCRIPTION
orderId String Order UUID

Returns

Order info result

placeOrder

HTTP Request

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

Description

EXPERIMENTAL API. Creates an order of a given type.

Parameters

PARAMETER TYPE DESCRIPTION
estimate Boolean Order estimation param. If set, order will not be created, and will be just calculated.
orderRequest OrderRequest Order request

Returns

Placed order result PlacedOrderResult

termsConditions

HTTP Request

POST /aps/2/resources/{aps-id}/orders/termsconditions

Description

Returns a list of Terms & Conditions that should be accepted by end-customer

Returns

updateReason

HTTP Request

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

Description

Update a correction reason validation with specified params.

Parameters

PARAMETER TYPE DESCRIPTION
updateReasonRequest CorrectionReasonValidationRequest A request with params to be updated in the correction reason

Returns

Structures

CorrectionReasonValidationInfo

A correction reason validation info for given vendor and language, returned by a rest endpoint.

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
invalidMessage String Not Required   An invalid message which is displayed if a user entered a correction reason which is not complies with given pattern
pattern String Not Required   A validation pattern (a regular expression) against which a correction reason entered by a user should be validated

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
messages LocalizedCorrectionReasonMessage array 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
pattern String Not Required   A validation pattern (a regular expression) against which a correction reason entered by a user should be validated

CorrectionReasonValidationRequest

A request for creating a correction reason validation info with given params.

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
messages LocalizedCorrectionReasonMessage array 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
pattern String Not Required   A validation pattern (a regular expression) against which a correction reason entered by a user should be validated

Currency

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
code String Not Required   Currency ISO code.
value Real Not Required   Currency amount.

DiscountReport

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
amount Real Not Required   Difference between the initial price and the discounted price.
type   Not Required   Specifies if the discount is a fixed sum or percent of the initial price.
value Real Not Required   Discount value, either a fixed sum or percent of the initial price.

Duration

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
duration Real Required    
unit   Required    

LocalizedCorrectionReasonMessage

This APS structure represents a localized invalid message for a correction reason validation process. This message is shown if a reason entered by a user is invalid, and it is specific for given locale.

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
invalidMessage String Not Required   An invalid message which is displayed if a user entered a correction reason which is not complies with a pattern (the pattern is specified in CorrectionReasonValidationRequest)
locale String Not Required   A locale for which an invalid message is displayed. Locale string complies with the Java local rules. It may be in three forms, e.g.: “en”, “en_US”, “en_US_SiliconValley”

OrderDetailDTO

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
description String Not Required   Localized description of the order detail.
discount DiscountReport Not Required   Report on the applied discount; can be null.
duration Duration Not Required   Duration of the order detail the price is calculated for.
exclusiveTaxAmount Currency Not Required   Exclusive tax that will be added to the initial price.
extendedPrice Currency Not Required   Total of the order detail calculated as unitPrice multiplied by quantity and multiplied by the duration.
lowerBound Real Not Required   In a case when the Tiered or Volume pricing model is used, this is the lower limit of a tier.
period Period Not Required   Subscription period of the service plan.
planId   Not Required   APS ID of the service plan.
quantity Real Not Required   Quantity of the ordered resources.
resourceId   Not Required   APS ID of the resource if the order detail is bound with a resource or null otherwise.
sku String Not Required   SKU.
taxAmount Currency 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).
taxCalcError String Not Required   Error message returned in a case of tax calculation failure.
type   Not Required   Type of the order detail.
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 Currency Not Required   Price per unit.

OrderEstimationResult

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
details OrderDetailDTO array Not Required   Array of the order details.
exclusiveTaxTotal Currency Not Required   Estimated order exclusive tax total.
promoResult   Not Required   Indicates the result of the attempt to apply the promotion.
subTotal Currency Not Required   Estimated order total without exclusive taxes.
taxTotal Currency Not Required   Estimated order tax total.
total Currency Not Required   Estimated order total.

OrderInfo

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
buyerId   Not Required    
creationTime Date Not Required    
expirationDate Date Not Required    
ofStatus String Not Required    
orderDate Date Not Required    
orderId   Not Required   Order identifier.
orderNumber String Not Required   Order number.
paymentStatus enum PaymentStatus Not Required    
provisioningStatus enum ProvisioningStatus Not Required    
sellerId   Not Required    
status enum OrderStatus Not Required   Order status.
type String Not Required    

OrderRequest

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
type   Not Required    

Period

Subscription period duration and type structure.

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
duration Integer Required   Duration of subscription period.
unit   Required   Subscription period unit.

PlacedOrderResult

Placed order result.

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
orderId   Not Required   Placed order UUID.

TermCondition

NAME TYPE ATTRIBUTES DEFAULT DESCRIPTION
content String Not Required    
name String Not Required    
termId String Not Required    

Examples

Since the considered APS type contains custom operations, refer to Custom Operations for the general explanation of their structure and examples of operation calls.