openapi: 3.2.0 info: title: Mef Charge API version: '1.0' description: 'Operations tagged charge across 2 of this provider''s published API definitions: mef-lso-cantata-product-order-management-openapi.yml, mef-lso-sonata-product-order-management-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://{serverBase}/mefApi/cantata/productOrderingManagement/v6/ variables: serverBase: description: The base of Seller's URL. default: mplify.net - url: https://{serverBase}/mefApi/sonata/productOrderingManagement/v11/ variables: serverBase: description: The base of Seller's URL. default: mplify.net tags: - name: charge paths: /charge: get: tags: - charge summary: Lists or finds Charge objects description: This operation lists or finds Charge entities operationId: listCharge parameters: - name: productOrderId in: query description: id of the Product Order this Charge relates to. required: false schema: type: string - name: productOrderItemId in: query description: id of the Product Order Item this Charge relates to. required: false schema: type: string - name: creationDate.gt in: query description: Date that the Charge was created by the Seller (greater than) required: false schema: type: string format: date-time - name: creationDate.lt in: query description: Date that the Charge was created by the Seller. (greater than) required: false schema: type: string format: date-time - name: responseDueDate.gt in: query description: The date that the Buyer must respond to the Seller's Charge. If there is no response received by the Due Date the Seller will treat all charges as declined (greater than) required: false schema: type: string format: date-time - name: responseDueDate.lt in: query description: The date that the Buyer must respond to the Seller's Charge. If there is no response received by the Due Date the Seller will treat all charges as declined (greater than) required: false schema: type: string format: date-time - name: buyerId in: query description: The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string - name: offset in: query description: Requested index for start of item to be provided in response requested by client. Note that the index starts with "0". required: false schema: type: integer format: int32 - name: limit in: query description: Requested number of items to be provided in response requested by client required: false schema: type: integer format: int32 responses: '200': description: Success headers: X-Pagination-Throttled: description: 'Used to indicate that result page was throttled to maximum possible size and there are additional results that can be fetched ' schema: type: boolean X-Total-Count: description: 'The total number of matching items. E.g. if there are 50 matching items in total, but the request has offset=10 and limit=10, then the X-Total-Count is 50. ' schema: type: integer X-Result-Count: description: The number of items included in the response schema: type: integer content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/MEFProductOrderCharge_Find' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '501': description: Method not implemented. content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error501' servers: - url: https://{serverBase}/mefApi/cantata/productOrderingManagement/v6/ variables: serverBase: description: The base of Seller's URL. default: mplify.net /charge/{id}: get: tags: - charge summary: Retrieves a Charge by ID description: This operation retrieves a Charge entity. operationId: retrieveCharge parameters: - name: id in: path description: Identifier of the Charge required: true schema: type: string - name: buyerId in: query description: The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string responses: '200': description: Success content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/MEFProductOrderCharge' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '501': description: Method not implemented. content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error501' patch: tags: - charge summary: Updates partially a Charge description: This operation updates partially a Charge entity. operationId: patchCharge parameters: - name: id in: path description: Identifier of the Charge required: true schema: type: string - name: buyerId in: query description: The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string requestBody: description: The Charge to be updated content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/MEFProductOrderCharge_Update' required: true responses: '200': description: Updated (https://tools.ietf.org/html/rfc7231#section-6.3.1) content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/MEFProductOrderCharge' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '409': description: Conflict content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error409' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '501': description: Method not implemented. content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error501' servers: - url: https://{serverBase}/mefApi/cantata/productOrderingManagement/v6/ variables: serverBase: description: The base of Seller's URL. default: mplify.net components: schemas: TimeUnit: description: 'Represents a unit of time. ' type: string enum: - seconds - minutes - businessHours - calendarHours - businessDays - calendarDays - months - years MEFAcceptedRejectedType: description: Indicator of acceptance type: string enum: - accepted - rejected MEFPriceCategory: description: A description of the cause of the Charge Item type: string enum: - cancellation - construction - connection - disconnect - expedite - other MEFProductOrderChargeActivityType: description: 'Possible values for the state of the Charge Activity Type ' type: string enum: - new - change MEFProductOrderItemRef: description: It's a ProductOrder item type: object properties: productOrderHref: description: Reference of the related ProductOrder. type: string productOrderId: description: Unique identifier of a ProductOrder. type: string productOrderItemId: description: Id of an Item within the Product Order type: string required: - productOrderId - productOrderItemId Note: description: Extra information about a given entity. Only useful in processes involving human interaction. Not applicable for the automated process. type: object properties: author: description: Author of the note type: string date: description: Date the Note was created type: string format: date-time id: description: Identifier of the note within its containing entity (may or may not be globally unique, depending on provider implementation) type: string source: description: Indicates if the note is from Buyer or Seller $ref: '#/components/schemas/MEFBuyerSellerType' text: description: Text of the note type: string required: - author - date - id - source - text MEFProductOrderCharge: description: When non-recurring or updated recurring charges are identified by the Seller during their processing of a Product Order, the Seller must communicate these charges to the Buyer and the Buyer must respond to the Seller informing the Seller if they accept or reject each charge. The Seller indicates for each charge, if the charge is Blocking or non-Blocking. If the Buyer rejects a Blocking Charge, the Seller will cancel that Product Order Item and any related Product Order Items. If the Buyer rejects a non-blocking Charge, the Seller may proceed with fulfillment of the Product Order Item. type: object properties: cancelProductOrder: description: A reference to the Cancel Product Order request that is cause of the Charge. Required if the Charge was caused by a Cancel Product Order. $ref: '#/components/schemas/MEFCancelProductOrderRef' chargeItem: description: A list of Charge Items contained in the Charge type: array items: $ref: '#/components/schemas/MEFProductOrderChargeItem' creationDate: description: Date that the Charge was created by the Seller. type: string format: date-time href: description: 'Hyperlink to the Charge. Hyperlink MAY be used by the Seller in responses Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request ' type: string id: description: A unique identifier of the Charge type: string modifyProductOrderItemRequestedDeliveryDate: description: A reference to the Modify Product Order Item Requested Delivery Date request that is cause of the Charge. Required if the Charge was caused by a Modify Product Order Item Requested Delivery Date request. $ref: '#/components/schemas/MEFModifyProductOrderItemRequestedDeliveryDateRef' productOrder: description: Product Order which the Seller is communicating additional or modified charges to the Buyer. This relation MUST be set when the Charge applies to a Product Order. (Caused by Cancel Product Order request) $ref: '#/components/schemas/MEFProductOrderRef' productOrderItem: description: Product Order Item which the Seller is communicating additional or modified charges to the Buyer. This relation MUST be set when the Charge applies to a Product Order Item. (Identified by Seller or caused by Modify Product Order Item Requested Delivery Date request) $ref: '#/components/schemas/MEFProductOrderItemRef' responseDueDate: description: The date by which the Buyer must respond to the Seller's Charge. If there is no response received by the Due Date the Seller will treat all charges as declined and move them to `declinedByBuyer` status and put the Charge to `completed` status. type: string format: date-time state: description: The state of the Charge $ref: '#/components/schemas/MEFProductOrderChargeStateType' required: - chargeItem - creationDate - id - responseDueDate - state MEFCancelProductOrderRef: description: A reference to a Cancel Product Order instance type: object properties: href: description: Hyperlink to access the Cancel Product Order type: string id: description: A unique identifier of the Cancel Product Order type: string required: - id Duration: description: A Duration in a given unit of time e.g. 3 hours, or 5 days. type: object properties: amount: description: Duration (number of seconds, minutes, hours, etc.) type: integer minimum: 0 units: description: Time unit enumerated $ref: '#/components/schemas/TimeUnit' required: - amount - units Error403Code: description: 'This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users' type: string enum: - accessDenied - forbiddenRequester - tooManyUsers MEFProductOrderCharge_Find: description: A response object for Buyer's get Charge List request. type: object properties: creationDate: description: Date that the Charge was created by the Seller. type: string format: date-time id: description: A unique identifier of the Charge type: string productOrder: description: Product Order which the Seller is communicating additional or modified charges to the Buyer. This relation MUST be set when the Charge applies to a Product Order. (Caused by Cancel Product Order request) $ref: '#/components/schemas/MEFProductOrderRef' productOrderItem: description: Product Order Item which the Seller is communicating additional or modified charges to the Buyer. This relation MUST be set when the Charge applies to a Product Order Item. (Identified by Seller or caused by Modify Product Order Item Requested Delivery Date request) $ref: '#/components/schemas/MEFProductOrderItemRef' responseDueDate: description: The date by which the Buyer must respond to the Seller's Charge. If there is no response received by the Due Date the Seller will treat all charges as declined and move them to `declinedByBuyer` status and put the Charge to `completed` status. type: string format: date-time state: description: The state of the Charge $ref: '#/components/schemas/MEFProductOrderChargeStateType' required: - creationDate - id - responseDueDate - state Error401Code: description: 'One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired' type: string enum: - missingCredentials - invalidCredentials MEFProductOrderChargeStateType: description: 'Possible values for the state of the Charge | State | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `completed` | All Charge Items included in the Charge for a given Product Order Item have moved to either the `accepted` state or the `declined` state. | | `awaitingResponse` | A Charge has been initiated by the Buyer. The charge includes one or more charges. | | `timeout` | A response has not been received from the Buyer within the `responseDueDate`. This is treated as if the Buyer declined the Charge Items. | | `withdrawnBySeller` | The Seller determines that the Charge is incorrect. They withdraw the Charge and initiate a new Charge with the required correction(s). | ' type: string enum: - awaitingResponse - completed - timeout - withdrawnBySeller Error400: description: Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: 'One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body' $ref: '#/components/schemas/Error400Code' required: - code MEFModifyProductOrderItemRequestedDeliveryDateRef: description: a reference to Modify Product Order Item Requested Delivery Date type: object properties: href: description: Hyperlink to access the Modify Product Order Item Requested Delivery Date type: string id: description: A unique identifier of the Modify Product Order Item Requested Delivery Date type: string required: - id Error500: description: Internal Server Error. (https://tools.ietf.org/html/rfc7231#section-6.6.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: 'The following error code: - internalError: Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request.' type: string enum: - internalError required: - code MEFProductOrderChargeItemStateType: description: 'Possible values for the state of the Charge Item | State | MEF 57.2 Name | Description | | ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `awaitingResponse` | AWAITING_RESPONSE | A Charge has been initiated by the Buyer. The charge includes one or more charges related to a Product Order or Product Order Item. Buyer has not indicated whether they accept or reject the charges via a Respond to Charge request. | | `completed` | COMPLETED | All Charge Items included in the Charge have moved to either the `acceptedByBuyer` state, the `declinedByBuyer` state, or the `withdrawnBySeller` state. | | `timeout` | TIMEOUT | A Charge Item has been declined by the Buyer. The referenced Product Order and Product Order Items are updated. If a Blocking charge is declined, the Seller may cancel the referenced Product Order Item and any related Product Order Items, the related Cancel Product Order, or the related Modify Product Order Item Requested Delivery Date. | | `withdrawnBySeller` | WITHDRAWN_BY_SELLER | The Seller determines that the Charge Item is incorrect. They withdraw the Charge Item and initiate a new Charge with the required correction(s) if needed. | ' type: string enum: - awaitingResponse - acceptedByBuyer - declinedByBuyer - withdrawnBySeller Price: description: Provides all amounts (tax included, duty-free, tax rate) and used currency of a Price type: object properties: dutyFreeAmount: description: All taxes excluded amount (expressed in the given currency) $ref: '#/components/schemas/Money' taxIncludedAmount: description: All taxes included amount (expressed in the given currency) $ref: '#/components/schemas/Money' taxRate: description: 'Price Tax Rate. Unit: [%]. E.g. value 16 stand for 16% tax.' type: number format: float required: - dutyFreeAmount Error400Code: description: 'One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body' type: string enum: - missingQueryParameter - missingQueryValue - invalidQuery - invalidBody MEFProductOrderChargeItem_Update: description: A type used to perform Buyer's response to a Charge Item - to accept or reject it. type: object properties: acceptanceIndicator: description: Indicates if the Buyer has accepted the specified charge $ref: '#/components/schemas/MEFAcceptedRejectedType' id: description: An identifier that is unique among Charge. Used for Charge Item matching, not to be update. type: string note: description: 'Free form text to clarify or explain the Charge Item. Only new notes can be entered. The Seller cannot modify an existing Note. ' type: array items: $ref: '#/components/schemas/Note' required: - acceptanceIndicator - id MEFProductOrderRef: description: Holds the MEF Product Order reference type: object properties: productOrderHref: description: Hyperlink to access the order type: string productOrderId: description: Unique (within the ordering domain) identifier for the order that is generated by the seller when the order is initially accepted. type: string required: - productOrderId MEFBuyerSellerType: description: Indicates if the note is from Buyer or Seller. type: string enum: - buyer - seller MEFPriceType: description: Indicates if the price is for recurring or non-recurring charges. type: string enum: - recurring - nonRecurring - usageBased MEFProductOrderCharge_Update: description: A subset of MEFProductOrderCharge that is allowed to be updated by the Buyer type: object properties: chargeItem: description: A list of Charge Items contained in the Charge type: array minItems: 1 items: $ref: '#/components/schemas/MEFProductOrderChargeItem_Update' required: - chargeItem Error401: description: Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: 'One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired' $ref: '#/components/schemas/Error401Code' required: - code Error501: description: Not Implemented. Used in case Seller is not supporting an optional operation (https://tools.ietf.org/html/rfc7231#section-6.6.2) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: 'The following error code: - notImplemented: Method not supported by the server' type: string enum: - notImplemented required: - code Error: description: 'Standard Class used to describe API response error Not intended to be used directly. The `code` in the HTTP header is used as a discriminator for the type of error returned in runtime. ' type: object properties: message: description: Text that provides mode details and corrective actions related to the error. This can be shown to a client user. type: string reason: description: Text that explains the reason for the error. This can be shown to a client user. type: string maxLength: 255 referenceError: description: URL pointing to documentation describing the error type: string format: uri required: - reason Money: description: A base/value business entity used to represent money type: object properties: unit: description: Currency (ISO4217 norm uses 3 letters to define the currency) type: string value: description: A positive floating point number type: number format: float required: - unit - value Error422: description: Unprocessable entity due to a business validation problem. (https://tools.ietf.org/html/rfc4918#section-11.2) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: "One of the following error codes:\n - missingProperty: The property the Seller has expected is not present in the payload\n - invalidValue: The property has an incorrect value\n - invalidFormat: The property value does not comply with the expected value format\n - referenceNotFound: The object referenced by the property cannot be identified in the Seller system\n - unexpectedProperty: Additional property, not expected by the Seller has been provided\n - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.\n - otherIssue: Other problem was identified (detailed information provided in a reason)\n" $ref: '#/components/schemas/Error422Code' propertyPath: description: 'A pointer to a particular property of the payload that caused the validation issue. It is highly recommended that this property should be used. Defined using JavaScript Object Notation (JSON) Pointer (https://tools.ietf.org/html/rfc6901). ' type: string required: - code Error422Code: description: "One of the following error codes:\n - missingProperty: The property the Seller has expected is not present in the payload\n - invalidValue: The property has an incorrect value\n - invalidFormat: The property value does not comply with the expected value format\n - referenceNotFound: The object referenced by the property cannot be identified in the Seller system\n - unexpectedProperty: Additional property, not expected by the Seller has been provided\n - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.\n - otherIssue: Other problem was identified (detailed information provided in a reason)\n" type: string enum: - missingProperty - invalidValue - invalidFormat - referenceNotFound - unexpectedProperty - tooManyRecords - otherIssue Error404: description: Resource for the requested path not found. (https://tools.ietf.org/html/rfc7231#section-6.5.4) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: 'The following error code: - notFound: A current representation for the target resource not found' type: string enum: - notFound required: - code Error403: description: Forbidden. This code indicates that the server understood the request but refuses to authorize it. (https://tools.ietf.org/html/rfc7231#section-6.5.3) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: 'This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users' $ref: '#/components/schemas/Error403Code' required: - code Error409: description: Conflict (https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.8) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: 'The following error code: - conflict: The client has provided a value whose semantics are not appropriate for the property.' type: string enum: - conflict required: - code MEFProductOrderChargeItem: description: A single component part of the Charge type: object properties: acceptanceIndicator: description: Indicates if the Buyer has accepted the specified charge. $ref: '#/components/schemas/MEFAcceptedRejectedType' activityType: description: Indicates if this is a new charge or a change to a charge provided in a Quote or in a previous accepted Charge Item. $ref: '#/components/schemas/MEFProductOrderChargeActivityType' blocking: description: Indicates if rejecting the charge will cause the Seller to cancel the Product Order Item, or close the Cancel Product Order or Modify Product Order Item Requested Delivery Date without action. type: boolean id: description: An identifier that is unique among all Charge Items within a Charge type: string note: description: 'Free form text to clarify or explain the Charge Item. Only new notes can be entered. The Seller cannot modify an existing Note. ' type: array items: $ref: '#/components/schemas/Note' price: description: The value of the Price associated with the Charge Item $ref: '#/components/schemas/Price' priceCategory: description: The category of the price $ref: '#/components/schemas/MEFPriceCategory' priceType: description: The type of the price. $ref: '#/components/schemas/MEFPriceType' recurringChargePeriod: description: Used for a Charge Item with a priceType = recurring to indicate the period $ref: '#/components/schemas/Duration' state: description: The state of the Charge Item $ref: '#/components/schemas/MEFProductOrderChargeItemStateType' unitOfMeasure: description: Unit of Measure if price depending on it is usageBased (Gb, SMS volume, etc..) type: string required: - activityType - blocking - id - price - priceCategory - priceType - state x-refined-from: - mef-lso-cantata-product-order-management-openapi.yml - mef-lso-sonata-product-order-management-openapi.yml