**TMF API Reference : TMF 637 - Product Inventory Management**.
swagger: '2.0'
info:
title: TMF637- Product Inventory Management
description: |+
**TMF API Reference : TMF 637 - Product Inventory Management**
version: 4.0.0
host: serverRoot
basePath: /tmf-api/productInventory/v4/
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
tags:
- name: product
- name: notification listeners (client side)
- name: events subscription
security:
- ApiKeyAuth: []
- OAuth2: []
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: https://api.mtn.com/v1/oauth/access_token
paths:
/product:
get:
operationId: listProduct
summary: List or find Product objects
description: This operation list or find Product entities
tags:
- product
parameters:
- name: customerNodeId
description: Identifier of the customer. SV_MAPPING:CUSTOMER_NODE_TRE_V.CUSTOMER_NODE_ID
required: false
type: string
in: query
- name: planName
description: Identifier of the offer display name. SV_MAPPING:PRODUCT_NSTANCE_TRE_V.PRODUCT_OFFER_DISPLAY_NAME. Default to All. Supports comma separated list of values
required: false
type: string
in: query
- name: offerIds
description: Identifier of the offer id. SV_MAPPING:PRODUCT_OFFER_TRE_V.PRODUCT_OFFER_ID. Supports comma separated list of values
required: false
type: string
in: query
- name: serviceName
description: Identifier of the service name. SV_MAPPING:SERVICE_TRE_V.SERVICE_NAME. Support wildcard. If wildcard is provided, then 'LIKE' SQL operator is enforced by the API, otherwise '=' is used.
required: false
type: string
in: query
- name: subscriberName
description: Identifier of the subscriber name. SV_MAPPING:PERSON_TRE_V.OFFICIAL_NAME. Support wildcard. If wildcard is provided, then 'LIKE' SQL operator is enforced by the API, otherwise '=' is used.
required: false
type: string
in: query
- name: subscriptionStatus
description: SV_MAPPING:PRODUCT_INSTANCE_TRE_V.PRODUCT_INSTANCE_STATUS_CODE. Refer to RT perestapi.imp.PRODUCT_INSTANCE_STATUS. Default to All
required: false
type: string
in: query
- name: includeStatus
description: 'Filter for base product instances status. If set to ''All'', all instances will be returned regardless the status. If set to ''Cancelled'', only all Cancelled, Moved and Upgraded status instances will be included in the main query. If set to Non-Cancelled, then all instances will be included in the main query except for Cancelled, Moved and Upgraded status instances. Default is set to ''All''. SV_MAPPING: RT perestapi.INCLUDE_STATUS'
required: false
type: string
in: query
x-refdata-source: RT-perestapi.INCLUDE_STATUS
- name: sortKey
description: To sort the response based on sortKey. Possible values - validFor. These values are retrieved from RT perestapi.imp.product.SORT_KEY
required: false
in: query
type: string
- name: sortOrder
description: To sort the response based on sort order. Possible value ascending, descending. Default to descending if sortKey is provided.
required: false
in: query
type: string
- name: offset
description: Requested index for start of resources to be provided in response. Default to 0
required: false
in: query
type: integer
format: int64
- name: limit
description: Requested number of resources to be provided in response. Default to configuration item API_CONFIGURATION1.DEFAULT_MAX_ROWS
required: false
in: query
type: integer
format: int64
- name: scn
description: Oracle system change number used for data read consistency. Default to emtpy string if configuration item API_CONFIGURATION1.USE_FLASHBACK is not ON
required: false
in: query
type: string
- name: fields
description: Comma-separated properties to provide in response
required: false
type: string
in: query
responses:
'200':
description: Success
headers:
X-Result-Count:
description: Actual number of items returned in the response body
type: integer
X-Total-Count:
description: Total number of items matching criteria
type: integer
schema:
$ref: '#/definitions/Product'
'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'
/product/{id}:
get:
operationId: retrieveProduct
summary: Retrieves a Product by ID
description: This operation retrieves a Product entity. Attribute selection is enabled for all first level attributes.
tags:
- product
parameters:
- name: id
description: Identifier of the Product
required: true
type: string
in: path
- name: fields
description: Comma-separated properties to provide in response
required: false
type: string
in: query
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Product'
'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.
required:
- id
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.
AttachmentRefOrValue:
type: object
description: An attachment by value or by reference.
properties:
id:
type: string
description: Unique identifier for this particular attachment. For Product Offer images SV_MAPPING:IMG<ProductOfferId>-(1..n), For Product Offer Help SV_MAPPING:HLP<ProductOfferId>
attachmentType:
type: string
description: Attachment type such as help urls, video, picture. For Product Offer images SV_MAPPING:image, For Product Offer Help SV_MAPPING:document
name:
type: string
description: The name of the attachment. For Product Offer images SV_MAPPING:ImageUrl-(1..n), For Product Offer Help SV_MAPPING:HelpUrl
url:
type: string
description: Uniform Resource Locator, is a web page address (a subset of URI). SV_MAPPING:PRODUCT_OFFER.PRODUCT_OFFER_IMAGE_URLS, PRODUCT_OFFER.PRODUCT_OFFER_HELP_URL
Any: {}
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.
Bucket:
type: object
description: Describes allocation consumption details
properties:
initialQuantity:
description: SV_MAPPING:ENTITLEMENT_ALLOCATION_TRE_V.INITIAL_AMOUNT
$ref: '#/definitions/Quantity'
balanceQuantity:
description: SV_MAPPING:ENTITLEMENT_ALLOCATION_TRE_V.CONSUMED_AMOUNT
$ref: '#/definitions/Quantity'
consumptionPeriod:
description: It is from SV_MAPPING:ENTITLEMENT_ALLOCATION_TRE_V.START_DATE to SV_MAPPING:ENTITLEMENT_ALLOCATION_TRE_V.EXPIRY_DATE
$ref: '#/definitions/TimePeriod'
id:
type: string
description: Id of the entitlement allocation. SV_MAPPING:ENTITLEMENT_ALLOCATION_TRE_V.ENTITLEMENT_ALLOCATION_ID
CategoryRef:
type: object
description: The category for grouping recommendations
required:
- id
properties:
id:
type: string
description: Unique identifier of a related entity. SV_MAPPING:perestapi.imp.CATEGORY->Ref Code
href:
type: string
description: Reference of the category - <http:/<PEREST_HOSTNAME>:<PEREST_PORT>/<Category PEREST URL>/<perestapi.imp.CATEGORY->Ref Code>
name:
type: string
description: Name of the related entity. SV_MAPPING:perestapi.dCatalogCategory->Category Name
codeLabel:
type: string
description: Code Label corresponding to the category name. SV_MAPPING:perestapi.imp.CATEGORY->Code Label
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
dispSequence:
type: integer
format: int64
description: Sequence or order in which particular attribute is shown on user interface
configurable:
type: string
description: If 'True', it indicates that the Characteristic is configurable/updatable, otherwise 'False'
enabled:
type: string
description: 'If ''True'', it indicates that the Characteristic is enabled to be supplied/selected at the time of selling. SV_MAPPING: RT BOOLEAN -> Abbreviation'
id:
type: string
description: Identifier of the attribute which identifies characteristic uniquely. Example - Attribute Type Id
'@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
CharacteristicRef:
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
'@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
GeographicAddress:
type: object
description: Structured textual way of describing how to find a Property for service installation
properties:
street1:
type: string
description: 'Line 1, SV_MAPPING: SERVICE_TRE_V.A_LINE_1, SERVICE_TRE_V.B_LINE_1'
street2:
type: string
description: 'Line 2, SV_MAPPING: SERVICE_TRE_V.A_LINE_2, SERVICE_TRE_V.B_LINE_2'
suburb:
type: string
description: 'Suburban, SV_MAPPING: SERVICE_TRE_V.A_SUBURB, SERVICE_TRE_V.B_SUBURB'
city:
type: string
description: 'City, SV_MAPPING: SERVICE_TRE_V.A_CITY, SERVICE_TRE_V.B_CITY'
postCode:
type: string
description: 'Post Code, SV_MAPPING: SERVICE_TRE_V.A_POST_CODE, SERVICE_TRE_V.B_POST_CODE'
stateOrProvince:
type: string
description: 'State, SV_MAPPING: SERVICE_TRE_V.A_STATE, SERVICE_TRE_V.B_STATE'
country:
type: string
description: 'Country, SV_MAPPING: SERVICE_TRE_V.A_COUNTRY, SERVICE_TRE_V.B_COUNTRY'
addressLine1:
type: string
description: 'Address line 1, SV_MAPPING: SERVICE_TRE_V.A_GENERAL_1, SERVICE_TRE_V.B_GENERAL_1'
geocode:
type: string
description: 'Geo Code providing geographical coordinates corresponding to a location, SV_MAPPING: SERVICE_TRE_V.A_GEOCODE, SERVICE_TRE_V.B_GEOCODE'
buildingId:
type: string
description: 'Building Id as used for serviceability. SV_MAPPING: SERVICE_TRE_V.A_GENERAL_2, SERVICE_TRE_V.B_GENERAL_2'
region:
type: string
description: 'Region as used for serviceability. SV_MAPPING: SERVICE_TRE_V.A_GENERAL_5, SERVICE_TRE_V.B_GENERAL_5'
subDoorNumber:
type: string
description: 'Sub Door Number as used for serviceability. SV_MAPPING: SERVICE_TRE_V.A_GENERAL_3, SERVICE_TRE_V.B_GENERAL_3'
genericAddress:
type: string
description: 'Generic Address as used for serviceability. SV_MAPPING: SERVICE_TRE_V.A_GENERAL_4, SERVICE_TRE_V.B_GENERAL_4'
addressId:
type: string
description: 'Address ID of the service address as used for serviceability. SV_MAPPING: SERVICE_HISTORY.A_ADDRESS_ID, SERVICE_HISTORY.B_ADDRESS_ID'
xpos:
type: number
format: float
description: 'X coordinate of the geographic address, SV_MAPPING: SERVICE_TRE_V.A_XPOS | SERVICE_TRE_V.B_XPOS'
ypos:
type: number
format: float
description: 'Y coordinate of the geographic address, SV_MAPPING: SERVICE_TRE_V.A_YPOS | SERVICE_TRE_V.B_YPOS'
'@type':
type: string
description: This is used to differentiate service address types as 'A' and 'B'
x-refdata-source: CM-Address_Type
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
PaginationRef:
type: object
description: Query results and paging details.
properties:
offset:
type: integer
format: int64
description: Requested index for start of items to be provided in response
limit:
type: integer
format: int64
description: Requested number of items to be provided in response
remainingRecords:
type: integer
format: int64
description: Remaining number of items to be fetched
totalRecords:
type: integer
format: int64
description: Total number of items matching criteria
scn:
type: string
description: Oracle system change number for read consistency
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
tax:
type: array
items:
$ref: '#/definitions/TaxItem'
description: An amount of money levied on the price of a Product by a legislative body.
priceCharacteristic:
type: array
items:
$ref: '#/definitions/Characteristic'
description: Additional attributes that describe price.
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:
id:
type: string
description: unique id of this resource.
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
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:
pagination:
description: Query results and paging details.
$ref: '#/definitions/PaginationRef'
productDetails:
type: array
items:
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'
productCharacteristic:
type: array
items:
$ref: '#/definitions/Characteristic'
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
Product_Create:
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).
Skipped properties: id,href
required:
- status
properties:
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'
productCharacteristic:
type: array
items:
$ref: '#/definitions/Characteristic'
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
Product_Update:
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).
Skipped properties: id,href
properties:
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:
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-tmf637-product-inventory.yml