The Product Inventory API provides standardized access to product instances subscribed by customers, enabling product lifecycle management operations including provisioning, suspension, termination, and status queries.
openapi: 3.0.1
info:
title: ProductInventory
description: >+
**TMF API Reference : TMF 637 - Product Inventory Management**
September 2023
The Product Inventory Management API provides standardized mechanism for product inventory
management such as creation, update and retrieval of the representation of a product in the
inventory. It also allows the notification of events related to product lifecycle
**Product resource**
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).
Product Inventory API performs the following operations on product :
- Retrieval of a product or a collection of products depending on filter criteria
- Partial update of a product (including updating rules and for administration purpose)
- Creation of a product (including default values and creation rules and for administration
purpose)
- Deletion of a product (for administration purposes)
- Notification of events on product.
Copyright © TM Forum 2021. All Rights Reserved
version: 5.0.0
servers:
- url: 'https://serverRoot'
tags:
- name: product
description: Operations for Product Resource
- name: notification listener
description: Notifications for Resource Lifecycle and event notifications
- name: events subscription
description: Endpoints to register and terminate an Event Listener
paths:
/hub:
post:
operationId: createHub
summary: TM Forum Create a Subscription (hub) to Receive Events
description: Sets the communication endpoint to receive Events.
tags:
- events subscription
requestBody:
$ref: '#/components/requestBodies/Hub_FVO'
responses:
'201':
$ref: '#/components/responses/Hub'
default:
$ref: '#/components/responses/Error'
'/hub/{id}':
delete:
operationId: hubDelete
summary: TM Forum Remove a Subscription (hub) to Receive Events
description: ''
tags:
- events subscription
parameters:
- $ref: '#/components/parameters/Id'
responses:
'204':
description: Deleted
default:
$ref: '#/components/responses/Error'
/listener/productAttributeValueChangeEvent:
post:
tags:
- notification listener
summary: TM Forum Client Listener for Entity ProductAttributeValueChangeEvent
description: Example of a client listener for receiving the notification ProductAttributeValueChangeEvent
operationId: productAttributeValueChangeEvent
requestBody:
$ref: '#/components/requestBodies/ProductAttributeValueChangeEvent'
responses:
'204':
description: Notified
default:
$ref: '#/components/responses/Error'
/listener/productCreateEvent:
post:
tags:
- notification listener
summary: TM Forum Client Listener for Entity ProductCreateEvent
description: Example of a client listener for receiving the notification ProductCreateEvent
operationId: productCreateEvent
requestBody:
$ref: '#/components/requestBodies/ProductCreateEvent'
responses:
'204':
description: Notified
default:
$ref: '#/components/responses/Error'
/listener/productDeleteEvent:
post:
tags:
- notification listener
summary: TM Forum Client Listener for Entity ProductDeleteEvent
description: Example of a client listener for receiving the notification ProductDeleteEvent
operationId: productDeleteEvent
requestBody:
$ref: '#/components/requestBodies/ProductDeleteEvent'
responses:
'204':
description: Notified
default:
$ref: '#/components/responses/Error'
/listener/productProductBatchEvent:
post:
tags:
- notification listener
summary: TM Forum Client Listener for Entity ProductProductBatchEvent
description: Example of a client listener for receiving the notification ProductProductBatchEvent
operationId: productProductBatchEvent
requestBody:
$ref: '#/components/requestBodies/ProductProductBatchEvent'
responses:
'204':
description: Notified
default:
$ref: '#/components/responses/Error'
/listener/productStateChangeEvent:
post:
tags:
- notification listener
summary: TM Forum Client Listener for Entity ProductStateChangeEvent
description: Example of a client listener for receiving the notification ProductStateChangeEvent
operationId: productStateChangeEvent
requestBody:
$ref: '#/components/requestBodies/ProductStateChangeEvent'
responses:
'204':
description: Notified
default:
$ref: '#/components/responses/Error'
/product:
get:
tags:
- product
summary: TM Forum List or Find Product Objects
description: List or find Product objects
operationId: listProduct
parameters:
- $ref: '#/components/parameters/Fields'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
$ref: '#/components/responses/200ProductArray'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
post:
tags:
- product
summary: TM Forum Creates a Product
description: This operation creates a Product entity.
operationId: createProduct
parameters:
- $ref: '#/components/parameters/Fields'
requestBody:
$ref: '#/components/requestBodies/Product_FVO'
responses:
'201':
$ref: '#/components/responses/201Product'
'202':
description: Accepted
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'409':
$ref: '#/components/responses/409'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
'/product/{id}':
get:
tags:
- product
summary: TM Forum Retrieves a Product by ID
description: >-
This operation retrieves a Product entity. Attribute selection enabled for all first level
attributes.
operationId: retrieveProduct
parameters:
- $ref: '#/components/parameters/Id'
- $ref: '#/components/parameters/Fields'
responses:
'200':
$ref: '#/components/responses/200Product_Get'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
delete:
tags:
- product
summary: TM Forum Deletes a Product
description: This operation deletes a Product entity.
operationId: deleteProduct
parameters:
- $ref: '#/components/parameters/Id'
responses:
'202':
$ref: '#/components/responses/202'
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'409':
$ref: '#/components/responses/409'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
patch:
tags:
- product
summary: TM Forum Updates Partially a Product
description: This operation updates partially a Product entity.
operationId: patchProduct
parameters:
- $ref: '#/components/parameters/Id'
- $ref: '#/components/parameters/Fields'
requestBody:
$ref: '#/components/requestBodies/Product_MVO'
responses:
'200':
$ref: '#/components/responses/200Product_Patch'
'202':
description: Accepted
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'409':
$ref: '#/components/responses/409'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
components:
schemas:
AccountRef:
type: object
description: Account reference. A account may be a party account or a financial account.
allOf:
- $ref: '#/components/schemas/EntityRef'
discriminator:
propertyName: '@type'
mapping:
AccountRef: '#/components/schemas/AccountRef'
AccountRef_FVO:
type: object
description: Account reference. A account may be a party account or a financial account.
allOf:
- $ref: '#/components/schemas/EntityRef_FVO'
discriminator:
propertyName: '@type'
mapping:
AccountRef: '#/components/schemas/AccountRef_FVO'
AccountRef_MVO:
type: object
description: Account reference. A account may be a party account or a financial account.
allOf:
- $ref: '#/components/schemas/EntityRef'
discriminator:
propertyName: '@type'
mapping:
AccountRef: '#/components/schemas/AccountRef_MVO'
Addressable:
type: object
description: Base schema for adressable entities
properties:
href:
type: string
description: Hyperlink reference
id:
type: string
description: unique identifier
Addressable_FVO:
type: object
description: Base schema for adressable entities
properties:
id:
type: string
description: unique identifier
AgreementItemRef:
allOf:
- $ref: '#/components/schemas/Extensible'
- type: object
description: It's a Agreement item that has been executed previously.
properties:
agreementName:
type: string
description: Name of the related entity.
agreementHref:
type: string
description: Reference of the related entity.
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
agreementId:
type: string
description: Unique identifier of a related entity.
agreementItemId:
type: string
description: Id of an item of a Agreement
discriminator:
propertyName: '@type'
mapping:
AgreementItemRef: '#/components/schemas/AgreementItemRef'
AgreementItemRef_FVO:
allOf:
- $ref: '#/components/schemas/Extensible_FVO'
- type: object
description: It's a Agreement item that has been executed previously.
properties:
agreementName:
type: string
description: Name of the related entity.
agreementHref:
type: string
description: Reference of the related entity.
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
agreementId:
type: string
description: Unique identifier of a related entity.
agreementItemId:
type: string
description: Id of an item of a Agreement
required:
- agreementId
- agreementItemId
discriminator:
propertyName: '@type'
mapping:
AgreementItemRef: '#/components/schemas/AgreementItemRef_FVO'
AgreementItemRef_MVO:
allOf:
- $ref: '#/components/schemas/Extensible'
- type: object
description: It's a Agreement item that has been executed previously.
properties:
agreementName:
type: string
description: Name of the related entity.
agreementHref:
type: string
description: Reference of the related entity.
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
agreementId:
type: string
description: Unique identifier of a related entity.
agreementItemId:
type: string
description: Id of an item of a Agreement
discriminator:
propertyName: '@type'
mapping:
AgreementItemRef: '#/components/schemas/AgreementItemRef_MVO'
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.
allOf:
- $ref: '#/components/schemas/Extensible'
- $ref: '#/components/schemas/EntityRef'
discriminator:
propertyName: '@type'
mapping:
AgreementRef: '#/components/schemas/AgreementRef'
AgreementRef_FVO:
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.
allOf:
- $ref: '#/components/schemas/Extensible_FVO'
- $ref: '#/components/schemas/EntityRef_FVO'
discriminator:
propertyName: '@type'
mapping:
AgreementRef: '#/components/schemas/AgreementRef_FVO'
AgreementRef_MVO:
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.
allOf:
- $ref: '#/components/schemas/Extensible'
- $ref: '#/components/schemas/EntityRef'
discriminator:
propertyName: '@type'
mapping:
AgreementRef: '#/components/schemas/AgreementRef_MVO'
Attachment:
allOf:
- $ref: '#/components/schemas/Entity'
- type: object
description: >-
Complements the description of an element (for instance a product) through video,
pictures...
properties:
name:
type: string
description: The name of the attachment
description:
type: string
description: A narrative text describing the content of the attachment
example: Photograph of the Product
url:
type: string
description: 'Uniform Resource Locator, is a web page address (a subset of URI)'
example: 'http://host/Content/4aafacbd-11ff-4dc8-b445-305f2215715f'
content:
type: string
format: base64
description: 'The actual contents of the attachment object, if embedded, encoded as base64'
size:
$ref: '#/components/schemas/Quantity'
validFor:
$ref: '#/components/schemas/TimePeriod'
attachmentType:
type: string
description: >-
a business characterization of the purpose of the attachment, for example logo,
instructionManual, contractCopy
mimeType:
type: string
description: a technical characterization of the attachment content format using IETF Mime Types
discriminator:
propertyName: '@type'
mapping:
Attachment: '#/components/schemas/Attachment'
AttachmentRef:
allOf:
- $ref: '#/components/schemas/EntityRef'
- type: object
description: >-
Attachment reference. An attachment complements the description of an element (for
instance a product) through video, pictures
properties:
description:
type: string
description: A narrative text describing the content of the attachment
url:
description: Link to the attachment media/content
type: string
discriminator:
propertyName: '@type'
mapping:
AttachmentRef: '#/components/schemas/AttachmentRef'
AttachmentRefOrValue:
type: object
description: >-
The polymorphic attributes @type, @schemaLocation & @referredType are related to the
Attachment entity and not the AttachmentRefOrValue class itself
oneOf:
- $ref: '#/components/schemas/Attachment'
- $ref: '#/components/schemas/AttachmentRef'
discriminator:
propertyName: '@type'
mapping:
Attachment: '#/components/schemas/Attachment'
AttachmentRef: '#/components/schemas/AttachmentRef'
AttachmentRefOrValue_FVO:
type: object
description: >-
The polymorphic attributes @type, @schemaLocation & @referredType are related to the
Attachment entity and not the AttachmentRefOrValue class itself
oneOf:
- $ref: '#/components/schemas/Attachment_FVO'
- $ref: '#/components/schemas/AttachmentRef_FVO'
discriminator:
propertyName: '@type'
mapping:
Attachment: '#/components/schemas/Attachment_FVO'
AttachmentRef: '#/components/schemas/AttachmentRef_FVO'
AttachmentRefOrValue_MVO:
type: object
description: >-
The polymorphic attributes @type, @schemaLocation & @referredType are related to the
Attachment entity and not the AttachmentRefOrValue class itself
oneOf:
- $ref: '#/components/schemas/Attachment_MVO'
- $ref: '#/components/schemas/AttachmentRef_MVO'
discriminator:
propertyName: '@type'
mapping:
Attachment: '#/components/schemas/Attachment_MVO'
AttachmentRef: '#/components/schemas/AttachmentRef_MVO'
AttachmentRef_FVO:
allOf:
- $ref: '#/components/schemas/EntityRef_FVO'
- type: object
description: >-
Attachment reference. An attachment complements the description of an element (for
instance a product) through video, pictures
properties:
description:
type: string
description: A narrative text describing the content of the attachment
url:
description: Link to the attachment media/content
type: string
discriminator:
propertyName: '@type'
mapping:
AttachmentRef: '#/components/schemas/AttachmentRef_FVO'
AttachmentRef_MVO:
allOf:
- $ref: '#/components/schemas/EntityRef'
- type: object
description: >-
Attachment reference. An attachment complements the description of an element (for
instance a product) through video, pictures
properties:
description:
type: string
description: A narrative text describing the content of the attachment
url:
description: Link to the attachment media/content
type: string
discriminator:
propertyName: '@type'
mapping:
AttachmentRef: '#/components/schemas/AttachmentRef_MVO'
Attachment_FVO:
allOf:
- $ref: '#/components/schemas/Entity_FVO'
- type: object
description: >-
Complements the description of an element (for instance a product) through video,
pictures...
properties:
name:
type: string
description: The name of the attachment
description:
type: string
description: A narrative text describing the content of the attachment
example: Photograph of the Product
url:
type: string
description: 'Uniform Resource Locator, is a web page address (a subset of URI)'
example: 'http://host/Content/4aafacbd-11ff-4dc8-b445-305f2215715f'
content:
type: string
format: base64
description: 'The actual contents of the attachment object, if embedded, encoded as base64'
size:
$ref: '#/components/schemas/Quantity'
validFor:
$ref: '#/components/schemas/TimePeriod'
attachmentType:
type: string
description: >-
a business characterization of the purpose of the attachment, for example logo,
instructionManual, contractCopy
mimeType:
type: string
description: a technical characterization of the attachment content format using IETF Mime Types
required:
- attachmentType
- mimeType
discriminator:
propertyName: '@type'
mapping:
Attachment: '#/components/schemas/Attachment_FVO'
Attachment_MVO:
allOf:
- $ref: '#/components/schemas/Entity_MVO'
- type: object
description: >-
Complements the description of an element (for instance a product) through video,
pictures...
properties:
name:
type: string
description: The name of the attachment
description:
type: string
description: A narrative text describing the content of the attachment
example: Photograph of the Product
url:
type: string
description: 'Uniform Resource Locator, is a web page address (a subset of URI)'
example: 'http://host/Content/4aafacbd-11ff-4dc8-b445-305f2215715f'
content:
type: string
format: base64
description: 'The actual contents of the attachment object, if embedded, encoded as base64'
size:
$ref: '#/components/schemas/Quantity'
validFor:
$ref: '#/components/schemas/TimePeriod'
attachmentType:
type: string
description: >-
a business characterization of the purpose of the attachment, for example logo,
instructionManual, contractCopy
mimeType:
type: string
description: a technical characterization of the attachment content format using IETF Mime Types
discriminator:
propertyName: '@type'
mapping:
Attachment: '#/components/schemas/Attachment_MVO'
BaseEvent:
allOf:
- $ref: '#/components/schemas/Entity'
- type: object
description: Base event with common attributes.
properties:
event:
type: object
eventId:
type: string
description: The identifier of the notification.
eventTime:
type: string
format: date-time
description: Time of the event occurrence.
eventType:
type: string
description: The type of the notification.
correlationId:
type: string
description: The correlation id for this event.
domain:
type: string
description: The domain of the event.
title:
type: string
description: The title of the event.
description:
type: string
description: An explanatory of the event.
priority:
type: string
description: A priority.
timeOcurred:
type: string
format: date-time
description: The time the event occured.
discriminator:
propertyName: '@type'
mapping:
BaseEvent: '#/components/schemas/BaseEvent'
BaseEvent_FVO:
allOf:
- $ref: '#/components/schemas/Entity'
- type: object
description: Base event with common attributes.
properties:
event:
type: object
eventId:
type: string
description: The identifier of the notification.
eventTime:
type: string
format: date-time
description: Time of the event occurrence.
eventType:
type: string
description: The type of the notification.
correlationId:
type: string
description: The correlation id for this event.
domain:
type: string
description: The domain of the event.
title:
type: string
description: The title of the event.
description:
type: string
description: An explanatory of the event.
priority:
type: string
description: A priority.
timeOcurred:
type: string
format: date-time
description: The time the event occured.
discriminator:
propertyName: '@type'
mapping:
BaseEvent: '#/components/schemas/BaseEvent_FVO'
BaseEvent_MVO:
allOf:
- $ref: '#/components/schemas/Entity_MVO'
- type: object
description: Base event with common attributes.
properties:
event:
type: object
eventId:
type: string
description: The identifier of the notification.
eventTime:
type: string
format: date-time
description: Time of the event occurrence.
eventType:
type: string
description: The type of the notification.
correlationId:
type: string
description: The correlation id for this event.
domain:
type: string
description: The domain of the event.
title:
type: string
description: The title of the event.
description:
type: string
description: An explanatory of the event.
priority:
type: string
description: A priority.
timeOcurred:
type: string
format: date-time
description: The time the event occured.
discriminator:
propertyName: '@type'
mapping:
BaseEvent: '#/components/schemas/BaseEvent_MVO'
BillingAccountRef:
allOf:
- $ref: '#/components/schemas/Extensible'
- $ref: '#/components/schemas/EntityRef'
- type: object
description: >-
BillingAccount reference. A BillingAccount is a detailed description of a bill
structure.
properties:
ratingType:
type: string
description: >-
Indicates whether the account follows a specific payment option such as prepaid or
postpaid
discriminator:
propertyName: '@type'
mapping:
BillingAccountRef: '#/components/schemas/BillingAccountRef'
BillingAccountRef_FVO:
allOf:
- $ref: '#/components/schemas/Extensible_FVO'
- $ref: '#/components/schemas/EntityRef_FVO'
- type: object
description: >-
BillingAccount reference. A BillingAccount is a detailed description of a bill
structure.
properties:
ratingType:
type: string
description: >-
Indicates whether the account follows a specific payment option such as prepaid or
postpaid
discriminator:
propertyName: '@type'
mapping:
BillingAccountRef: '#/components/schemas/BillingAccountRef_FVO'
BillingAccountRef_MVO:
allOf:
- $ref: '#/components/schemas/Extensible'
- $ref: '#/components/schemas/EntityRef'
- type: object
description: >-
BillingAccount reference. A BillingAccount is a detailed description of a bill
structure.
properties:
ratingType:
type: string
description: >-
Indicates whether the account follows a specific payment option such as prepaid or
postpaid
discriminator:
propertyName: '@type'
mapping:
BillingAccountRef: '#/components/schemas/BillingAccountRef_MVO'
BooleanArrayCharacteristic:
allOf:
- $ref: '#/components/schemas/Characteristic'
- type: object
description: A characteristic which value is an array of Boolean(s).
properties:
value:
type: array
items:
type: boolean
BooleanArrayCharacteristic_FVO:
allOf:
- $ref: '#/components/schemas/Characteristic_FVO'
- type: object
description: A characteristic which value is an array of Boolean(s).
properties:
value:
type: array
items:
type: boolean
required:
- value
BooleanArrayCharacteristic_MVO:
allOf:
- $ref: '#/components/schemas/Characteristic_MVO'
- type: object
description: A characteristic which value is an array of Boolean(s).
properties:
value:
type: array
items:
type: boolean
required:
- value
BooleanCharacteristic:
allOf:
- $ref: '#/components/schemas/Characteristic'
- type: object
description: A characteristic which value is a Boolean.
properties:
value:
type: boolean
description: Value of the characteristic
BooleanCharacteristic_FVO:
allOf:
- $ref: '#/components/schemas/Characteristic_FVO'
- type: object
description: A characteristic which value is a Boolean.
properties:
value:
type: boolean
description: Value of the characteristic
required:
- value
BooleanCharacteristic_MVO:
allOf:
- $ref: '#/components/schemas/Characteristic_MVO'
- type: object
description: A characteristic which value is a Boolean.
properties:
value:
type: boolean
description: Value of the characteristic
required:
- value
BusinessPartner:
type: object
description: 'When business partner is the BusinessPartner '
allOf:
- $ref: '#/components/schemas/PartyRole'
BusinessPartner_FVO:
type: object
description: 'When business partner is the BusinessPartner '
allOf:
- $ref: '#/components/schemas/PartyRole_FVO'
BusinessPartner_MVO:
type: object
description: 'When business partner is the BusinessPartner '
allOf:
- $ref: '#/components/schemas/PartyRole_MVO'
CalendarPeriod:
allOf:
- $ref: '#/components/schemas/Extensible'
- type: object
properties:
day:
type: string
des
# --- truncated at 32 KB (307 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tm-forum/refs/heads/main/openapi/tm-forum-tmf637-product-inventory-openapi.yaml