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.

← Order Management

Payment Management →