swagger: '2.0'
info:
title: Product Ordering
description: |+
A Product Order is a type of order which can be used to place an order between a customer and a service provider or between a service provider and a partner and vice versa.
Main Product Order attributes are its identifier, state, priority category (mass market, Enterprise, etc.) related dates (start, completion, etc.), related billing account, related parties and order items. Main Order Items (aka order lines) attributes are the ordered offering and product characteristics with the related action to be performed (e.g. add or delete the products), state, location information for delivery, order item price and price alteration.
version: 4.0.0
host: api.mtn.com
basePath: /tmf-api/productordering/v1
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: 'https://api.mtn.com/v1/oauth/access_token'
security:
- OAuth2: []
- ApiKeyAuth: []
tags:
- name: productOrder
paths:
/productOrder:
post:
operationId: createProductOrder
summary: Creates a ProductOrder
description: This operation creates a ProductOrder entity.
tags:
- productOrder
parameters:
- name: transactionId
in: header
type: string
description: The transaction Id for request tracing. This should be forwarded from the Process Layer.
- name: productOrder
description: The ProductOrder to be created
required: true
schema:
$ref: '#/definitions/ProductOrder_Create2'
in: body
responses:
'201':
description: Created
schema:
$ref: '#/definitions/CreateOrderResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/productOrder/{id}:
get:
operationId: retrieveProductOrder
summary: Retrieves a ProductOrder by customer ID
description: This operation retrieves a ProductOrder entity. Attribute selection is enabled for all first level attributes.
tags:
- productOrder
parameters:
- name: id
description: Identifier of the ProductOrder,i.e. Subscriber Identifier
required: true
type: string
in: path
- name: limit
description: the number of records/items to be returned
required: false
type: string
in: query
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ViewActiveVAS'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
delete:
operationId: deleteProductOrder
summary: Deletes a ProductOrder
description: This operation deletes a ProductOrder entity.
tags:
- productOrder
parameters:
- name: id
description: Identifier of the ProductOrder
required: true
type: string
in: path
- name: reason
required: true
in: header
type: string
enum:
- Not interested
- Inapprpriate
- Not valuable
- name: productOrder
description: The ProductOrder to be created
required: true
schema:
$ref: '#/definitions/productOrderDelete'
in: body
responses:
'204':
description: success
schema:
$ref: '#/definitions/CancelProductOrderResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
definitions:
AgreementItemRef:
type: object
description: Agreement reference. An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a number of other business entities, such as products, services, and resources and/or their specifications.
properties:
id:
type: string
description: Unique identifier of a related entity.
href:
type: string
description: Reference of the related entity.
agreementItemId:
type: string
description: Identifier of the agreement
name:
type: string
description: Name of the related entity.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
AgreementRef:
type: object
description: Agreement reference. An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a number of other business entities, such as products, services, and resources and/or their specifications.
required:
- id
properties:
id:
type: string
description: Unique identifier of a related entity.
href:
type: string
description: Reference of the related entity.
name:
type: string
description: Name of the agreement
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
Any: {}
AppointmentRef:
type: object
description: Refers an appointment, such as a Customer presentation or internal meeting or site visit
properties:
id:
type: string
description: The identifier of the referred appointment
href:
type: string
description: The reference of the appointment
description:
type: string
description: An explanatory text regarding the appointment made with a party
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation
required:
- id
BillingAccountRef:
type: object
description: BillingAccount reference. A BillingAccount is a detailed description of a bill structure.
required:
- id
properties:
id:
type: string
description: Unique identifier of the billing account
href:
type: string
description: Reference of the billing account
name:
type: string
description: Name of the billing account
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
CancelOrder:
type: object
description: A Order cancel is a type of task which can be used to place a request to cancel an order
properties:
id:
type: string
description: id of the cancellation request (this is not an order id)
href:
type: string
description: Hyperlink to access the cancellation request
cancellationReason:
type: string
description: Reason why the order is cancelled.
effectiveCancellationDate:
type: string
format: date-time
description: Date when the order is cancelled.
requestedCancellationDate:
type: string
format: date-time
description: Date when the submitter wants the order to be cancelled
state:
$ref: '#/definitions/TaskStateType'
description: Tracks the lifecycle status of the cancellation request, such as Acknowledged, Rejected, InProgress, Pending and so on.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
CancelProductOrder:
type: object
description: Request for cancellation an existing product order
required:
- productOrder
properties:
id:
type: string
description: id of the cancellation request (this is not an order id)
href:
type: string
description: Hyperlink to access the cancellation request
cancellationReason:
type: string
description: Reason why the order is cancelled.
effectiveCancellationDate:
type: string
format: date-time
description: Date when the order is cancelled.
requestedCancellationDate:
type: string
format: date-time
description: Date when the submitter wants the order to be cancelled
productOrder:
$ref: '#/definitions/ProductOrderRef'
state:
$ref: '#/definitions/TaskStateType'
description: Tracks the lifecycle status of the cancellation request, such as Acknowledged, Rejected, InProgress, Pending and so on.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
CancelProductOrder_Create:
type: object
description: |-
Request for cancellation an existing product order
Skipped properties: id,href,state,effectiveCancellationDate
required:
- productOrder
properties:
cancellationReason:
type: string
description: Reason why the order is cancelled.
requestedCancellationDate:
type: string
format: date-time
description: Date when the submitter wants the order to be cancelled
productOrder:
$ref: '#/definitions/ProductOrderRef'
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
Characteristic:
type: object
description: Describes a given characteristic of an object or entity through a name/value pair.
required:
- name
- value
properties:
name:
type: string
description: Name of the characteristic
valueType:
type: string
description: Data type of the value of the characteristic
value:
$ref: '#/definitions/Any'
description: The value of the characteristic
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
EntityRef:
type: object
description: Entity reference schema to be use for all entityRef class.
properties:
id:
type: string
description: Unique identifier of a related entity.
href:
type: string
description: Reference of the related entity.
name:
type: string
description: Name of the related entity.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
Money:
type: object
description: A base / value business entity used to represent money
properties:
unit:
type: string
description: Currency (ISO4217 norm uses 3 letters to define the currency)
value:
type: number
format: float
description: A positive floating point number
Note:
type: object
description: Extra information about a given entity
required:
- text
properties:
id:
type: string
description: Identifier of the note within its containing entity (may or may not be globally unique, depending on provider implementation)
author:
type: string
description: Author of the note
date:
type: string
format: date-time
description: Date of the note
text:
type: string
description: Text of the note
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
OrderItemActionType:
type: string
description: action to be performed on the product
enum:
- add
- modify
- delete
- noChange
OrderItemRelationship:
type: object
properties:
id:
type: string
relationshipType:
type: string
description: The type of order item relationship
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
OrderPrice:
type: object
description: An amount, usually of money, that represents the actual price paid by the Customer for this item or this order
properties:
description:
type: string
description: A narrative that explains in detail the semantics of this order item price.
name:
type: string
description: A short descriptive name such as "Subscription price".
priceType:
type: string
description: A category that describes the price, such as recurring, discount, allowance, penalty, and so forth
recurringChargePeriod:
type: string
description: Could be month, week...
unitOfMeasure:
type: string
description: Could be minutes, GB...
billingAccount:
$ref: '#/definitions/BillingAccountRef'
description: A reference to a billing account used for paid the order price charge
price:
$ref: '#/definitions/Price'
description: a structure used to define price amount
priceAlteration:
type: array
items:
$ref: '#/definitions/PriceAlteration'
description: a strucuture used to describe a price alteration
productOfferingPrice:
$ref: '#/definitions/ProductOfferingPriceRef'
description: An amount, usually of money, that is asked for or allowed when a ProductOffering is bought, rented, or leased. The price is valid for a defined period of time.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
OrderTerm:
type: object
description: Description of a productTerm linked to this orderItem. This represent a commitment with a duration
properties:
description:
type: string
description: Description of the productOrderTerm
name:
type: string
description: Name of the productOrderTerm
duration:
$ref: '#/definitions/Quantity'
description: Duration of the productOrderTerm
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
PaymentRef:
type: object
description: If an immediate payment has been done at the product order submission, the payment information are captured and stored (as a reference) in the order.
required:
- id
properties:
id:
type: string
description: Unique identifier of a related entity.
href:
type: string
description: Reference of the related entity.
name:
type: string
description: A name for the payment
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
Place:
type: object
description: Place reference. Place defines the places where the products are sold or delivered.
properties:
id:
type: string
description: Unique identifier of the place
href:
type: string
description: Unique reference of the place
name:
type: string
description: A user-friendly name for the place, such as [Paris Store], [London Store], [Main Home]
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
PlaceRef:
type: object
description: Place reference. PlaceRef defines the placeRefs where the products are sold or delivered.
properties:
id:
type: string
description: Unique identifier of a related entity.
href:
type: string
description: Reference of the related entity.
name:
type: string
description: Name of the related entity.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
Price:
type: object
description: Provides all amounts (tax included, duty free, tax rate), used currency and percentage to apply for Price Alteration.
properties:
percentage:
type: number
format: float
description: Percentage to apply for ProdOfferPriceAlteration
taxRate:
type: number
format: float
description: Tax rate
dutyFreeAmount:
$ref: '#/definitions/Money'
description: All taxes excluded amount (expressed in the given currency)
taxIncludedAmount:
$ref: '#/definitions/Money'
description: All taxes included amount (expressed in the given currency)
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
PriceAlteration:
type: object
description: Is an amount, usually of money, that modifies the price charged for an order item.
required:
- price
- priceType
properties:
applicationDuration:
type: integer
description: Duration during which the alteration applies on the order item price (for instance 2 months free of charge for the recurring charge)
description:
type: string
description: A narrative that explains in detail the semantics of this order item price alteration
name:
type: string
description: Name of the order item price alteration
priceType:
type: string
description: A category that describes the price such as recurring, one time and usage.
priority:
type: integer
description: Priority level for applying this alteration among all the defined alterations on the order item price
recurringChargePeriod:
type: string
description: Could be month, week...
unitOfMeasure:
type: string
description: Could be minutes, GB...
price:
$ref: '#/definitions/Price'
productOfferingPrice:
$ref: '#/definitions/ProductOfferingPriceRef'
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
product2:
type: object
description: A product offering procured by a customer or other interested party playing a party role. A product is realized as one or more service(s) and / or resource(s).
properties:
name:
type: string
description: Name of the product. It could be the same as the name of the product offering
id:
type: string
description: Unique identifier of the product
status:
type: string
description: status of the product
href:
type: string
description: Reference of the product
description:
type: string
description: Is the description of the product. It could be copied from the description of the Product Offering.
orderDate:
type: string
format: date-time
description: Is the date when the product was ordered
productOffering:
$ref: '#/definitions/ProductOfferingRef'
productCharacteristic:
$ref: '#/definitions/productCharacteristic'
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
productTerm:
type: array
items:
$ref: '#/definitions/ProductTerm'
Product:
type: object
description: A product offering procured by a customer or other interested party playing a party role. A product is realized as one or more service(s) and / or resource(s).
properties:
id:
type: string
description: Unique identifier of the product
href:
type: string
description: Reference of the product
description:
type: string
description: Is the description of the product. It could be copied from the description of the Product Offering.
isBundle:
type: boolean
description: If true, the product is a ProductBundle which is an instantiation of a BundledProductOffering. If false, the product is a ProductComponent which is an instantiation of a SimpleProductOffering.
isCustomerVisible:
type: boolean
description: If true, the product is visible by the customer.
name:
type: string
description: Name of the product. It could be the same as the name of the product offering
orderDate:
type: string
format: date-time
description: Is the date when the product was ordered
productSerialNumber:
type: string
description: Is the serial number for the product. This is typically applicable to tangible products e.g. Broadband Router.
startDate:
type: string
format: date-time
description: Is the date from which the product starts
terminationDate:
type: string
format: date-time
description: Is the date when the product was terminated
agreement:
type: array
items:
$ref: '#/definitions/AgreementItemRef'
billingAccount:
$ref: '#/definitions/BillingAccountRef'
place:
type: array
items:
$ref: '#/definitions/RelatedPlaceRefOrValue'
product:
type: array
items:
$ref: '#/definitions/ProductRefOrValue'
productOffering:
$ref: '#/definitions/ProductOfferingRef'
productOrderItem:
type: array
items:
$ref: '#/definitions/RelatedProductOrderItem'
productPrice:
type: array
items:
$ref: '#/definitions/ProductPrice'
productRelationship:
type: array
items:
$ref: '#/definitions/ProductRelationship'
productSpecification:
$ref: '#/definitions/ProductSpecificationRef'
productTerm:
type: array
items:
$ref: '#/definitions/ProductTerm'
realizingResource:
type: array
items:
$ref: '#/definitions/ResourceRef'
realizingService:
type: array
items:
$ref: '#/definitions/ServiceRef'
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
status:
$ref: '#/definitions/ProductStatusType'
description: Is the lifecycle status of the product.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
ProductOfferingPriceRef:
type: object
description: ProductPriceOffering reference. An amount, usually of money, that is asked for or allowed when a ProductOffering is bought, rented, or leased
properties:
id:
type: string
description: Unique identifier of a related entity.
href:
type: string
description: Reference of the related entity.
name:
type: string
description: Name of the related entity.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
ProductOfferingQualificationItemRef:
type: object
description: It's a productOfferingQualification item that has been executed previously.
required:
- id
- productOfferingQualificationId
properties:
id:
type: string
description: Id of an item of a product offering qualification
href:
type: string
description: Reference of the related entity.
name:
type: string
description: Name of the related entity.
productOfferingQualificationHref:
type: string
description: Reference of the related entity.
productOfferingQualificationId:
type: string
description: Unique identifier of a related entity.
productOfferingQualificationName:
type: string
description: Name of the related entity.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-product-ordering-coe.yml