MEF Customer Bill API

openapi: 3.2.0
info:
  title: Mef Customer Bill API
  version: 3.0.1
  description: 'Operations tagged Customer Bill across 2 of this provider''s published API definitions: mef-lso-cantata-billing-management-openapi.yml, mef-lso-sonata-billing-management-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{serverBase}/mefApi/cantata/customerBillManagement/v3/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
- url: https://{serverBase}/mefApi/sonata/customerBillManagement/v3/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
tags:
- name: Customer Bill
paths:
  /customerBill:
    get:
      tags:
      - Customer Bill
      summary: List or find CustomerBill objects
      description: This operation lists or finds CustomerBill entities
      operationId: listCustomerBill
      parameters:
      - name: billingAccount.id
        in: query
        description: An identifier for the Billing Account that is unique within the Seller.
        required: false
        schema:
          type: string
      - name: billingPeriod.startDateTime.lt
        in: query
        description: The date the Billing Period started - lower than.
        required: false
        schema:
          type: string
          format: date-time
      - name: billingPeriod.startDateTime.gt
        in: query
        description: The date the Billing Period started - greater than.
        required: false
        schema:
          type: string
          format: date-time
      - name: billingPeriod.endDateTime.lt
        in: query
        description: The date the Billing Period ended - lower than.
        required: false
        schema:
          type: string
          format: date-time
      - name: billingPeriod.endDateTime.gt
        in: query
        description: The date the Billing Period ended - greater than.
        required: false
        schema:
          type: string
          format: date-time
      - name: category
        in: query
        description: 'The category of Bill. One of the following:  - normal  - duplicate - trial'
        required: false
        schema:
          type: string
          enum:
          - normal
          - duplicate
          - trial
      - name: state
        in: query
        description: The state of the Bill Item.
        required: false
        schema:
          type: string
          enum:
          - generated
          - paymentDue
          - settled
      - name: offset
        in: query
        description: Requested index for start of resources to be provided in response.
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Requested number of resources to be provided in response.
        required: false
        schema:
          type: integer
      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 records. E.g. if there are 50 matching records 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 records included in the response
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerBill_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 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'
    servers:
    - url: https://{serverBase}/mefApi/cantata/customerBillManagement/v3/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
  /customerBill/{id}:
    get:
      tags:
      - Customer Bill
      summary: Retrieves a CustomerBill by ID
      description: This operation retrieves a CustomerBill entity.
      operationId: retrieveCustomerBill
      parameters:
      - name: id
        in: path
        description: Identifier of the CustomerBill
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerBill'
        '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'
    servers:
    - url: https://{serverBase}/mefApi/cantata/customerBillManagement/v3/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
  /customerBillItem/{id}:
    get:
      tags:
      - Customer Bill
      summary: Retrieves a CustomerBillItem by ID
      description: This operation retrieves a CustomerBillItem entity.
      operationId: retrieveCustomerBillItem
      parameters:
      - name: id
        in: path
        description: Identifier of the CustomerBillItem
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerBillItem'
        '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'
    servers:
    - url: https://{serverBase}/mefApi/cantata/customerBillManagement/v3/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
components:
  schemas:
    CustomerBillItemRef:
      description: 'A reference to a Customer Bill resource.

        '
      type: object
      properties:
        href:
          description: 'Hyperlink to the referenced Customer Bill.

            '
          type: string
        id:
          description: Identifier of the referenced Customer Bill.
          type: string
      required:
      - id
    PaymentItem:
      description: A payment that has been received.
      type: object
      properties:
        id:
          description: An identifier for the payment that is unique within the Buyer Billing Account and is assigned by the Seller.
          type: string
        amount:
          description: The amount of money received.
          $ref: '#/components/schemas/Money'
        paymentMethod:
          description: The specific means of payment.
          $ref: '#/components/schemas/PaymentMethod'
        paymentDate:
          description: The Date the payment was received.
          type: string
          format: date-time
      required:
      - id
    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
    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
    AttachmentURL:
      description: The URL pointing to an Attachment for download.
      type: object
      properties:
        url:
          description: The URL pointing to an Attachment for download.
          type: string
    BillingAccountRef:
      description: An identifier for the Billing Account that is unique within the Seller
      type: object
      properties:
        id:
          description: Unique-Identifier
          type: string
      required:
      - id
    CustomerBillStateType:
      description: 'The state of the Bill.


        | state                     | MEF 134 name               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

        | -----------------------   | ----------------------     | ------------------------------------------------------------------------------------------------------------------------------|

        | `generated`               | GENERATED                  | A Bill that has been created based on the completion of an Billing Cycle and an Bill Notification has been sent to the Buyer. |

        | `paymentDue`              | PAYMENT_DUE                | The Seller has completed their dispute process and they are expecting payment from the Buyer                                  |

        | `settled`                 | SETTLED                    | A Bill for which all payment due has been received or for which payment is due.                                               |                                            |

        '
      type: string
      enum:
      - generated
      - paymentDue
      - settled
    CustomerBillRunType:
      description: "The Billing cycle as set by the Seller.\n\n| Value      | MEF 134   | Description                                                                                                  |\n| ---------- | --------- | ------------------------------------------------------------------------------------------------------------ |\n| `onCycle`  | On_Cycle  | Bill created as a result of the normal Invoicing Cycle                                                       | \n| `offCycle` | Off_Cycle | Bill created outside the normal Invoicing Cycle.  This may be based on a Buyer request or for other reasons. |\n"
      type: string
      enum:
      - onCycle
      - offCycle
    FinancialAccountRef:
      description: A Financial Account within the Seller.
      type: object
      properties:
        id:
          description: An identifier for the Financial Account that is unique within the Seller and is assigned by the Seller.
          type: string
        href:
          description: Unique reference of the account
          type: string
        name:
          description: The name of the Financial Account.
          type: string
        type:
          description: The type of the Financial Account.
          type: string
      required:
      - id
    FieldedAddressRepresentation:
      description: A type of Address that has a discrete field and value for each type of boundary or identifier down to the lowest level of detail. For example "street number" is one field, "street name" is another field, etc.
      type: object
      properties:
        streetNr:
          description: Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses.
          type: string
        streetNrSuffix:
          description: The first street number suffix (in a street number range) or the suffix for the street number if there is no range
          type: string
        streetNrLast:
          description: Last number in a range of street numbers allocated to an Address
          type: string
        streetNrLastSuffix:
          description: Last street number suffix for a ranged Address
          type: string
        streetPreDirection:
          description: The direction of the street that appears before the Street Name
          type: string
        streetName:
          description: Name of the street or other street type
          type: string
        streetType:
          description: The type of street (e.g., alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf)
          type: string
        streetPostDirection:
          description: A modifier denoting a relative direction that appears after the Street Name.
          type: string
        poBox:
          description: Number identifying a specific location in a post office.
          type: string
        locality:
          description: An area of defined or undefined boundaries within a local authority or other legislatively defined area.
          type: string
        city:
          description: City in which the Address is located.
          type: string
        postcode:
          description: A descriptor for a postal delivery area used to speed and simplify the delivery of mail (also known as zip code)
          type: string
        postcodeExtension:
          description: 'The extension used on a postal code. Note: there are different use codes for this attribute depending upon the country.'
          type: string
        stateOrProvince:
          description: The State or Province in which the Address is located.
          type: string
        countryCode:
          description: Country in which the Address is located, defined using two characters as defined in ISO 3166
          type: string
          minLength: 2
          maxLength: 2
        subUnit:
          description: The Sub Unit represented as a list. This is a list to allow complex sub-unit information such as SUITE 42 ROOM A
          type: array
          items:
            $ref: '#/components/schemas/SubUnit'
        buildingName:
          description: 'The well-known name of a building that is located at this Address (e.g., where there is one Address for a campus).

            '
          type: string
        privateStreetNumber:
          description: Street number on a private street within the Address.
          type: string
        privateStreetName:
          description: Private streets internal to a property (e.g., a university) may have internal names that are not recorded by the land title office.
          type: string
        language:
          description: The language in which the address is expressed. It MUST use the ISO 639:2023 two letter code 639:2023
          type: string
          minLength: 2
          maxLength: 2
    CustomerBillCategory:
      description: "The type of Bill. \n\n| Value       | MEF 134   |Description                                                                                                                                                                    |\n| ----------- | --------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `normal`    | NORMAL    |An Bill for the Billing Cycle                                                                                                                                                  |\n| `duplicate` | DUPLICATE |A copy of an Bill that has been provided                                                                                                                                       |\n| `trial`     | TRIAL     |An Bill that is sent by the Seller to the Buyer for test Billing purposes to assist in assuring that their Billing implementations are compatible. The Trial Bill is not paid. |\n"
      type: string
      enum:
      - normal
      - duplicate
      - trial
    Error401Code:
      description: 'One of the following error codes:

        - missingCredentials: No credentials provided.

        - invalidCredentials: Provided credentials are invalid or expired'
      type: string
      enum:
      - missingCredentials
      - invalidCredentials
    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
    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
    CustomerBill_Find:
      description: A legal document generated by the Seller to the Buyer relating to charges associated to Products provided by the Seller to the Buyer.
      type: object
      properties:
        id:
          description: An identifier assigned to the Bill by the Seller.
          type: string
        billingAccount:
          description: An identifier for the Billing Account that is unique within the Seller and is assigned by the Seller.
          $ref: '#/components/schemas/BillingAccountRef'
        billNo:
          description: A number assigned to the Bill by the Seller.
          type: string
        billingPeriod:
          description: The Start and Stop Dates of the Billing Period.
          $ref: '#/components/schemas/TimePeriod'
        category:
          description: 'The type of Bill. One of the following:

            - normal

            - duplicate

            - trial

            '
          $ref: '#/components/schemas/CustomerBillCategory'
        state:
          description: The state of the Bill.
          $ref: '#/components/schemas/CustomerBillStateType'
      required:
      - billNo
      - category
      - id
      - state
    CustomerBillItem:
      description: One or more rows in a Bill that represent charges associated with a Product instance.
      type: object
      properties:
        id:
          description: The CustomerBillItem identifier.
          type: string
        href:
          description: Reference of the CustomerBillItem.
          type: string
        appliedTax:
          description: Taxes associated with the Bill Item.
          type: array
          items:
            $ref: '#/components/schemas/CustomerBillItemTax'
        appliedFee:
          type: array
          items:
            description: Fees associated with the Bill Item.
            $ref: '#/components/schemas/CustomerBillItemFee'
        customerBillItemType:
          description: The type of charge related to the Bill Item.
          $ref: '#/components/schemas/MEFPriceType'
        description:
          description: A text description of the charge.
          type: string
        periodCoverage:
          description: The start and end dates of Billing for the Bill Item.
          $ref: '#/components/schemas/TimePeriod'
        product:
          description: The reference to the Product that is the subject of the Item.
          $ref: '#/components/schemas/ProductRef'
        productOrderItem:
          description: Identifier of the POI with reference to the Product Order.
          $ref: '#/components/schemas/MEFProductOrderItemRef'
        productName:
          description: The name of the Product that is the subject of the Bill Item.
          type: string
        state:
          description: The state of the Bill Item.
          $ref: '#/components/schemas/CustomerBillItemStateType'
        taxExcludedAmount:
          description: The amount of money of the charge before taxes and fees are calculated and applied
          $ref: '#/components/schemas/Money'
        unit:
          description: The rate per unit for the Bill determined during or after the Billing Process.
          type: string
        unitRate:
          description: The rate per unit for the Bill determined during or after the Billing Process.
          $ref: '#/components/schemas/Money'
        unitQuantity:
          description: The number of units.
          type: number
      required:
      - appliedFee
      - appliedTax
      - customerBillItemType
      - description
      - id
      - periodCoverage
      - product
      - productName
      - productOrderItem
      - state
      - taxExcludedAmount
      - unit
      - unitQuantity
      - unitRate
    CustomerBillItemTax:
      description: The applied billing tax rate represents the taxes applied billing rate it refers to. It is calculated during the billing process.
      type: object
      properties:
        category:
          description: The category of the Tax.
          $ref: '#/components/schemas/CustomerBillItemTaxCategory'
        description:
          description: A description of the type of Tax.
          type: string
        rate:
          description: The rate at which the Tax is calculated.
          type: number
          format: float
        amount:
          description: The amount of money of the Tax.
          $ref: '#/components/schemas/Money'
    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
    PaymentMethod:
      description: The specific means of payment.
      type: string
      enum:
      - check
      - wireTransfer
      - electronic
      - cash
      - other
    MEFPriceType:
      description: The type of charge related to the Bill Item.
      type: string
      enum:
      - recurring
      - nonRecurring
      - usageBased
    CustomerBill:
      description: A legal document generated by the Seller to the Buyer relating to charges associated to Products provided by the Seller to the Buyer.
      type: object
      properties:
        id:
          description: An identifier assigned to the Bill by the Seller.
          type: string
        href:
          description: Bill's unique reference.
          type: string
        amountDue:
          description: The total amount of money with all taxes, fees, and credits applied that is due.
          $ref: '#/components/schemas/Money'
        appliedPayment:
          description: A list of details of a payment that has been received from the Buyer.
          type: array
          items:
            $ref: '#/components/schemas/AppliedPayment'
        billingAccount:
          description: An identifier for the Billing Account that is unique within the Seller and is assigned by the Seller.
          $ref: '#/components/schemas/BillingAccountRef'
        billCycle:
          description: The identifier of the Billing Cycle iteration.
          type: string
        billDate:
          description: Date the Bill was issued.
          type: string
          format: date-time
        billDocument:
          description: URL pointing to PDF file containing printable version of the Customer Bill.
          $ref: '#/components/schemas/AttachmentURL'
        billNo:
          description: A number assigned to the Bill by the Seller.
          type: string
        billingPeriod:
          description: The Start and Stop Dates of the Billing Period.
          $ref: '#/components/schemas/TimePeriod'
        category:
          description: 'The type of Bill. One of the following:

            - normal

            - duplicate

            - trial

            '
          $ref: '#/components/schemas/CustomerBillCategory'
        credits:
          description: Amount of credits included.
          $ref: '#/components/schemas/Money'
        customerBillItem:
          description: A reference to the Bill Items for this Bill.
          type: array
          items:
            $ref: '#/components/schemas/CustomerBillItemRef'
        discounts:
          description: Amount of discounts included.
          $ref: '#/components/schemas/Money'
        fees:
          description: Amount of fees included.
          $ref: '#/components/schemas/Money'
        financialAccount:
          description: A Financial Account within the Seller.
          $ref: '#/components/schemas/FinancialAccountRef'
        lastUpdate:
          description: The date when the Bill was last modified.
          type: string
          format: date-time
        paymentDueDate:
          description: The date by which payment of the Amount Due must be received by the Seller.
          type: string
          format: date-time
        runType:
          description: The Billing cycle as set by the Seller.
          $ref: '#/components/schemas/CustomerBillRunType'
        relatedContactInformation:
          description: A party related to this Bill.
          type: array
          items:
            $ref: '#/components/schemas/RelatedContactInformation'
        remainingAmount:
          description: An amount of money that still requires payment.
          $ref: '#/components/schemas/Money'
        state:
          description: The state of the Bill.
          $ref: '#/components/schemas/CustomerBillStateType'
        taxExcludedAmount:
          description: The amount of money due without taxes being calculated for the current Billing Cycle.
          $ref: '#/components/schemas/Money'
        taxIncludedAmount:
          description: The amount of money due with taxes being calculated for the current Billing Cycle.
          $ref: '#/components/schemas/Money'
        taxItem:
          description: A tax item is created for each tax rate and tax type used in the bill.
          type: array
          items:
            $ref: '#/components/schemas/TaxItem'
      required:
      - amountDue
      - appliedPayment
      - billCycle
      - billDate
      - billDocument
      - billNo
      - billingAccount
      - billingPeriod
      - category
      - credits
      - customerBillItem
      - discounts
      - fees
      - financialAccount
      - id
      - lastUpdate
      - paymentDueDate
      - relatedContactInformation
      - remainingAmount
      - runType
      - state
      - taxExcludedAmount
      - taxIncludedAmount
      - taxItem
    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
    SubUnit:
      description: Allows for sub unit identification
      type: object
      properties:
        subUnitNumber:
          description: The discriminator used for the subunit, often just a simple number but may also be a range.
          type: string
        subUnitType:
          description: The type of subunit e.g. BERTH, FLAT, PIER, SUITE, SHOP, TOWER, UNIT, WHARF.
          type: string
      required:
      - subUnitNumber
      - subUnitType
    TaxItem:
      description: A tax item is created for each tax rate and tax type used in the bill.
      type: object
      properties:
        taxCategory:
          description: The Tax Category for this tax item.
          type: string
        taxRate:
          description: The Tax Rate for this Tax Item.
          type: number
          format: float
        taxAmount:
          description: The amount of money calculated for this Tax Item.
          $ref: '#/components/schemas/Money'
    CustomerBillItemStateType:
      description: 'The state of the Bill Item.


        | state                      | MEF 134 name               | Description                                                                                                                                                                   |

        | -------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

        | `credit`                   | CREDIT                     | The Seller has agreed with the Buyer that disputed charges are in error and has provided a credit for the amount in error.                                                    |

        | `disputeBeingInvestigated` | DISPUTE_BEING_INVESTIGATED | A Buyer has disputed charges included in a Bill and those charges are in the Sellers Dispute Process. Dispu

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-customer-bill-api-openapi.yml