The Shopping Cart API provides a standardized mechanism for the management of shopping carts. Including creation, update, retrieval.
swagger: '2.0'
info:
title: MTN Shopping Cart Management API
description: |+
The Shopping Cart API provides a standardized mechanism for the management of shopping carts. Including creation, update, retrieval
version: 1.0.0
host: api.mtn.com
basePath: /tmf-api/shoppingCart/v1/
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
tags:
- name: shoppingCart
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:
- ApiKeyAuth: []
- OAuth2: []
paths:
/shoppingCart:
post:
operationId: createShoppingCartLogin
summary: This API will return the cart session cookie, to be used for all subsequent requests.
description: This operation creates a ShoppingCart entity. The session cookie created is unique per shopping cart and will identify each shopping cart
tags:
- shoppingCart
parameters:
- name: transactionId
in: header
type: string
description: unique transaction identifier
required: true
- name: customerType
type: string
in: header
description: target system of request
required: true
enum:
- CBUOnline
- name: shoppingCart
description: The ShoppingCart to be created
required: true
schema:
$ref: '#/definitions/ShoppingCart_CreateSession'
in: body
responses:
'201':
description: Created
schema:
$ref: '#/definitions/ShoppingCart_CreateSessionResponse'
'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'
/shoppingCart/{id}:
get:
operationId: retrieveShoppingCart
summary: Retrieves a ShoppingCart Information by ID
description: This operation retrieves a ShoppingCart entity.
tags:
- shoppingCart
parameters:
- name: id
description: Identifier of the ShoppingCart
required: true
type: string
in: path
- name: transactionId
in: header
type: string
description: unique transaction identifier
required: true
- name: customerType
type: string
in: header
description: target system of request
required: true
enum:
- CBUOnline
- name: cookie
type: string
in: header
x-example: JSESSIONID=rvUKhWtBRaC3zuyv_KxKQQmFq4tI0wla2D--0OBC46QKBGT4cMwI
description: The unique ID of the session is returned. This must be passed as it is in the header of all the next ATG API calls.
required: true
- name: callingSystem
in: query
type: string
required: false
description: This is an identifer for the calling system. eg. MTN App, Online Recharges, No Funds, NGMTNApp
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ShoppingCartListByIDSuccessResponse'
'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'
/shoppingCart/{id}/order:
patch:
operationId: createShoppingCart
summary: Creates a ShoppingCart order
description: This operation creates a ShoppingCart Order.
tags:
- shoppingCart
parameters:
- name: id
in: path
required: true
description: This parameter indicates which site the response must be given. eg. MTNSite, OnlineStore, EBU_CC, EBU_SME, NGMTNApp
type: string
- name: transactionId
in: header
type: string
description: unique transaction identifier
required: true
- name: customerType
type: string
in: header
description: target system of request
required: true
enum:
- CBUOnline
- name: cookie
type: string
in: header
x-example: JSESSIONID=rvUKhWtBRaC3zuyv_KxKQQmFq4tI0wla2D--0OBC46QKBGT4cMwI
description: The unique ID of the session is returned. This must be passed as it is in the header of all the next ATG API calls.
required: true
- name: shoppingCart
description: The ShoppingCart to be created
required: true
schema:
$ref: '#/definitions/ShoppingCart_UpdateOrder'
in: body
responses:
'201':
description: Created
schema:
$ref: '#/definitions/ShoppingCart_UpdateOrderResponse'
'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'
/shoppingCart/{id}/userInfo:
patch:
operationId: patchShoppingCartUserInfo
summary: Updates partially a ShoppingCart user's information
description: This operation updates partially a ShoppingCart user's information.
tags:
- shoppingCart
parameters:
- name: id
in: path
required: true
description: This parameter indicates which site the response must be given. eg. MTNSite, OnlineStore, EBU_CC, EBU_SME, NGMTNApp
type: string
- name: transactionId
in: header
type: string
description: unique transaction identifier
required: true
- name: customerType
type: string
in: header
description: target system of request
required: true
enum:
- CBUOnline
- name: cookie
type: string
in: header
x-example: JSESSIONID=rvUKhWtBRaC3zuyv_KxKQQmFq4tI0wla2D--0OBC46QKBGT4cMwI
description: The unique ID of the session is returned. This must be passed as it is in the header of all the next ATG API calls.
required: true
- name: shoppingCart
description: The ShoppingCart to be updated
required: true
schema:
$ref: '#/definitions/ShoppingCart_UpdateUserInfo'
in: body
responses:
'200':
description: Updated
schema:
$ref: '#/definitions/ShoppingCart_UpdateUserInfoResponse'
'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'
/shoppingCart/{id}/shippingInfo:
patch:
operationId: patchShoppingCartShippingInfo
summary: Updates partially a ShoppingCart's shipping information
description: This operation updates partially a ShoppingCart shipping information.
tags:
- shoppingCart
parameters:
- name: id
in: path
required: true
description: This parameter indicates which site the response must be given. eg. MTNSite, OnlineStore, EBU_CC, EBU_SME, NGMTNApp
type: string
- name: transactionId
in: header
type: string
description: unique transaction identifier
required: true
- name: customerType
type: string
in: header
description: target system of request
required: true
enum:
- CBUOnline
- name: cookie
type: string
in: header
x-example: JSESSIONID=rvUKhWtBRaC3zuyv_KxKQQmFq4tI0wla2D--0OBC46QKBGT4cMwI
description: The unique ID of the session is returned. This must be passed as it is in the header of all the next ATG API calls.
required: true
- name: shoppingCart
description: The ShoppingCart to be updated
required: true
schema:
$ref: '#/definitions/ShoppingCart_UpdateShippingInfo'
in: body
responses:
'200':
description: Updated
schema:
$ref: '#/definitions/ShoppingCart_UpdateShippingInfoResponse'
'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'
/shoppingCart/{id}/submitOrder:
patch:
operationId: patchSubmitOrder
summary: Updates an order for submission
description: This operation submits the order items to be processed.
tags:
- shoppingCart
parameters:
- name: id
in: path
required: true
description: This parameter indicates which site the response must be given. eg. MTNSite, OnlineStore, EBU_CC, EBU_SME, NGMTNApp
type: string
- name: transactionId
in: header
type: string
description: unique transaction identifier
required: true
- name: customerType
type: string
in: header
description: target system of request
required: true
enum:
- CBUOnline
- name: cookie
type: string
in: header
x-example: JSESSIONID=rvUKhWtBRaC3zuyv_KxKQQmFq4tI0wla2D--0OBC46QKBGT4cMwI
description: The unique ID of the session is returned. This must be passed as it is in the header of all the next ATG API calls.
required: true
- name: submitOrderRequest
description: The ShoppingCart to be updated
required: true
schema:
$ref: '#/definitions/ShoppingCart_SubmitOrder'
in: body
responses:
'200':
description: Updated
schema:
$ref: '#/definitions/ShoppingCart_UpdateSubmitOrderResponse'
'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:
ShoppingCart_SubmitOrder:
type: object
properties:
cartItem:
type: array
items:
$ref: "#/definitions/CartItemSubmitOrder"
contactMedium:
type: array
items:
$ref: "#/definitions/ContactMediumSubmitOrder"
ContactMediumSubmitOrder:
type: object
properties:
emailAddress:
type: string
socialNetworkId:
type: string
CartItemSubmitOrder:
type: object
properties:
product:
$ref: "#/definitions/SubmitOrderProductItem"
SubmitOrderProductItem:
type: object
properties:
description:
type: string
isCustomerVisible:
type: boolean
example: false
agreement:
type: array
items:
$ref: "#/definitions/AgreementItemValueOrRef"
productOrderItem:
type: array
items:
$ref: "#/definitions/ProductOrderItemRef"
relatedParty:
type: array
items:
$ref: "#/definitions/RelatedPartyOrderRef"
AgreementItemValueOrRef:
type: object
properties:
value:
type: string
ProductOrderItemRef:
type: object
properties:
productOrderId:
type: string
orderItemId:
type: string
ShoppingCart_UpdateSubmitOrderResponse:
type: object
properties:
statusCode:
type: string
example: "0000"
description: MADAPI canonical code
statusMessage:
type: string
example: "Successful"
transactionId:
type: string
description: A trace id for tracking request/response
example: "43843948394"
data:
$ref: "#/definitions/ShoppingCart_UpdateSubmitOrderResponseData"
ShoppingCart_UpdateSubmitOrderResponseData:
type: object
description: |-
Shopping Cart resource is used for the temporarily selection and reservation of product offerings in e-commerce, call center and retail purchase. Shopping cart supports purchase of both physical and digital goods and service (e.g. handset, telecom network service). Shopping Cart contain list of cart items, a reference to customer (partyRole) or contact medium in case customer not exist, and the total items price including promotions
Skipped properties: id,href,validFor,cartTotalPrice
properties:
id:
type: string
cartTotalPrice:
type: array
items:
$ref: "#/definitions/CartPriceOrder"
cartItem:
type: array
items:
$ref: '#/definitions/CartItemOrder'
relatedParty:
type: array
items:
$ref: "#/definitions/RelatedPartyOrderRef"
validFor:
$ref: "#/definitions/TimePeriod"
contactMedium:
type: array
items:
$ref: '#/definitions/ContactMediumOrderRef'
'@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
CartItemOrder:
type: object
properties:
status:
type: string
enum:
- INTIAL
id:
type: string
product:
$ref: "#/definitions/CartItemOrderProduct"
itemPrice:
type: array
items:
$ref: '#/definitions/CartPriceOrder'
'@type':
type: string
CartItemOrderProduct:
type: object
properties:
id:
type: string
description: Unique identifier of the product
name:
type: string
description: Name of the product. It could be the same as the name of the product offering
description:
type: string
description: Is the description of the product. It could be copied from the description of the Product Offering.
isCustomerVisible:
type: boolean
description: If true, the product is visible by the customer.
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
orderDate:
type: string
format: date-time
description: Is the date when the product was ordered
productTerm:
type: array
items:
$ref: "#/definitions/ProductTermOrderRef"
realizingResource:
type: array
items:
$ref: '#/definitions/ResourceRefOrder'
productCharacteristic:
type: array
items:
$ref: '#/definitions/CharacteristicOrder'
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedPartyOrderRef'
billingAccount:
type: array
items:
$ref: '#/definitions/RelatedPartyOrderRef'
productPrice:
type: array
items:
$ref: '#/definitions/ProductPriceOrderRef'
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
CartPriceOrder:
type: object
description: An amount, usually of money, that represents the actual price paid by the customer for this item. May represent the total price of the shopping cart or the total of the cart item depending on the relation
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".
unitOfMeasure:
type: string
description: Could be minutes, GB...
price:
$ref: '#/definitions/PriceOrder'
priceAlteration:
type: array
items:
$ref: '#/definitions/PriceAlterationOrderRef'
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
ProductTermOrderRef:
type: object
properties:
description:
type: string
description: Description of the productTerm
validFor:
$ref: '#/definitions/TimePeriod'
description: productTerm validity period
RelatedPartyOrderRef:
type: object
description: Related Entity reference. A related party defines party or party role linked to a specific entity.
properties:
id:
type: string
description: Unique identifier of a related entity.
name:
type: string
description: Name of the related entity.
PriceAlterationOrderRef:
required:
- price
properties:
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
unitOfMeasure:
type: string
description: Could be minutes, GB...
price:
$ref: '#/definitions/PriceOrder'
productOfferingPrice:
$ref: "#/definitions/ProductOfferingPriceOrder"
ProductOfferingPriceOrder:
type: object
properties:
value:
type: string
example: 0
id:
type: string
example: "manualAdjustmentTotal"
ResourceRefOrder:
type: object
properties:
id:
type: string
description: Unique identifier of a related entity.
value:
type: string
description: 'The resource value that can be used to identify a resource with a public key (e.g.: a tel nr, an msisdn)'
required:
- id
CharacteristicOrder:
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
value:
$ref: '#/definitions/Any'
description: The value of the characteristic
ProductPriceOrderRef:
type: object
description: An amount, usually of money, that represents the actual price paid by a Customer for a purchase, a rent or a lease of a Product. The price is valid for a defined period of time.
required:
- price
- priceType
properties:
price:
$ref: '#/definitions/PriceOrder'
ContactMediumOrderRef:
type: object
description: Indicates the contact medium that could be used to contact the party.
properties:
id:
type: string
characteristic:
$ref: '#/definitions/MediumCharacteristicOrderRef'
description: Any additional characteristic(s) of this contact medium
'@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
MediumCharacteristicOrderRef:
type: object
description: Describes the contact medium characteristics that could be used to contact a party (an individual or an organization)
properties:
title:
type: string
middleName:
type: string
lastName:
type: string
firstName:
type: string
emailAddress:
type: string
description: Full email address in standard format
phoneNumber:
type: string
description: The primary phone number of the contact
socialNetworkId:
type: string
description: Identifier as a member of a social network
'@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
ShoppingCart_CreateSession:
type: object
properties:
channel:
type: object
properties:
id:
type: string
description: This parameter indicates which site the response must be given. eg. MTNSite, OnlineStore, EBU_CC, EBU_SME, NGMTNApp
relatedParty:
type: object
properties:
id:
type: string
description: This is the unique identifier of the source channel
ShoppingCart_CreateSessionResponse:
type: object
required:
- statusCode
- statusMessage
- supportMessage
- transactionId
properties:
statusCode:
type: string
statusMessage:
type: string
supportMessage:
type: string
transactionId:
type: string
data:
type: object
properties:
cookie:
type: string
description: The unique ID of the session is returned. This must be passed as it is in the header of all the next ATG API calls. [Tony] - Rather call this sessionId
example: JSESSIONID=rvUKhWtBRaC3zuyv_KxKQQmFq4tI0wla2D--0OBC46QKBGT4cMwI
ShoppingCart_UpdateOrder:
type: object
description: |-
Shopping Cart resource is used for the temporarily selection and reservation of product offerings in e-commerce, call center and retail purchase. Shopping cart supports purchase of both physical and digital goods and service (e.g. handset, telecom network service). Shopping Cart contain list of cart items, a reference to customer (partyRole) or contact medium in case customer not exist, and the total items price including promotions
Skipped properties: id,href,validFor,cartTotalPrice
properties:
cartItem:
type: array
items:
$ref: '#/definitions/CartItemOrder'
ShoppingCartListByIDSuccessResponse:
type: object
properties:
statusCode:
type: string
example: "0000"
description: MADAPI canonical code
statusMessage:
type: string
example: "Successful"
transactionId:
type: string
description: A trace id for tracking request/response
example: "43843948394"
data:
$ref: "#/definitions/ShoppingCartListByIDSuccessResponseData"
ShoppingCartListByIDSuccessResponseData:
type: object
properties:
id:
type: string
description: Identifier of the cart item (generally it is a sequence number 01, 02, 03, ...) in the shopping cart
cartItem:
type: array
items:
$ref: "#/definitions/CartItemRef"
cartTotalPrice:
type: array
items:
$ref: "#/definitions/CartTotalPriceRef"
relatedParty:
$ref: "#/definitions/RelatedParty"
CartItemRef:
type: object
properties:
id:
type: string
description: Identifier of the cart item (generally it is a sequence number 01, 02, 03, ...) in the shopping cart
quantity:
type: integer
description: Quantity of cart items
product:
allOf:
- $ref: "#/definitions/ProductRef"
- properties:
productOffering:
$ref: "#/definitions/ProductOfferingRef"
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
productCharacteristic:
type: array
items:
$ref: "#/definitions/ProductCharacteristicRef"
productPrice:
type: array
items:
$ref: "#/definitions/PriceAlterationRef"
CartTotalPriceRef:
type: object
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".
unitOfMeasure:
type: string
description: Could be minutes, GB...
priceAlteration:
type: array
items:
$ref: "#/definitions/PriceAlterationRef"
price:
$ref: "#/definitions/PriceRef"
ProductCharacteristicRef:
type: object
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
PriceAlterationRef:
type: object
properties:
price:
$ref: "#/definitions/PriceRef"
PriceRef:
type: object
properties:
taxRate:
type: number
format: float
description: Tax rate
dutyFreeAmount:
$ref: "#/definitions/Money"
taxIncludedAmount:
$ref: "#/definitions/Money"
ShoppingCart_UpdateOrderResponse:
type: object
required:
- statusCode
- statusMessage
- supportMessage
- transactionId
properties:
statusCode:
type: string
statusMessage:
type: string
supportMessage:
type: string
transactionId:
type: string
description: It is a unique id for the transaction and it's request being issued.
data:
type: object
properties:
id:
type: string
description: The unique ID identifies the order ID to use when looking up the order.
example: o220001
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
Any: {}
BillingAccountRef:
type: object
description: BillingAccount reference. A BillingAccount is a detailed description of a bill structure.
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.
required:
- id
CartItem:
type: object
description: An identified part of the shopping cart. A shopping cart is decomposed into one or more shopping cart item. Cart item represents a product offering or bundled product offering that user wish to purchase, as well as the pricing of the product offering, reference to product in case of configured characteristic or installation address. Cart items can be related to other cart item to related bundled offerings or reference cart Items to a shipping
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-tmf633-shopping-cart-management.yml