openapi: 3.0.1 info: title: Product Catalog Management agreement billingAccount API description: "Product Catalog API is one of Catalog Management API Family. Product Catalog API goal is to provide a catalog of products. \n### Operations\nProduct Catalog API performs the following operations on the resources :\n- Retrieve an entity or a collection of entities depending on filter criteria\n- Partial update of an entity (including updating rules)\n- Create an entity (including default values and creation rules)\n- Delete an entity\n- Manage notification of events" version: 5.0.0 servers: - url: https://serverRoot/productCatalogManagement/v5/ tags: - name: billingAccount paths: /billingAccount: get: operationId: listBillingAccount summary: List or find BillingAccount objects description: This operation list or find BillingAccount entities tags: - billingAccount parameters: - name: fields description: Comma-separated properties to be provided in response required: false in: query type: string - name: offset description: Requested index for start of resources to be provided in response required: false in: query type: integer - name: limit description: Requested number of resources to be provided in response required: false in: query type: integer responses: '200': description: Success headers: X-Result-Count: description: Actual number of items returned in the response body type: integer X-Total-Count: description: Total number of items matching criteria type: integer schema: type: array items: $ref: '#/definitions/BillingAccount' '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' post: operationId: createBillingAccount summary: Creates a BillingAccount description: This operation creates a BillingAccount entity. tags: - billingAccount parameters: - name: billingAccount description: The BillingAccount to be created required: true schema: $ref: '#/definitions/BillingAccount_Create' in: body responses: '201': description: Created schema: $ref: '#/definitions/BillingAccount' '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' /billingAccount/{id}: get: operationId: retrieveBillingAccount summary: Retrieves a BillingAccount by ID description: This operation retrieves a BillingAccount entity. Attribute selection is enabled for all first level attributes. tags: - billingAccount parameters: - name: id description: Identifier of the BillingAccount required: true type: string in: path - name: fields description: Comma-separated properties to provide in response required: false type: string in: query responses: '200': description: Success schema: $ref: '#/definitions/BillingAccount' '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' patch: operationId: patchBillingAccount summary: Updates partially a BillingAccount description: This operation updates partially a BillingAccount entity. tags: - billingAccount parameters: - name: id description: Identifier of the BillingAccount required: true type: string in: path - name: billingAccount description: The BillingAccount to be updated required: true schema: $ref: '#/definitions/BillingAccount_Update' in: body responses: '200': description: Updated schema: $ref: '#/definitions/BillingAccount' '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' delete: operationId: deleteBillingAccount summary: Deletes a BillingAccount description: This operation deletes a BillingAccount entity. tags: - billingAccount parameters: - name: id description: Identifier of the BillingAccount required: true type: string in: path responses: '204': description: Deleted '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: BillingAccount_Create: type: object description: 'A party account used for billing purposes. It includes a description of the bill structure (frequency, presentation media, format and so on). It is a specialization of entity PartyAccount. Skipped properties: id,href' required: - name - relatedParty properties: accountType: type: string description: 'A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics. Note: for flexibility we use a String here but an implementation may use an enumeration with a limited list of valid values.' description: type: string description: Detailed description of the party account lastModified: type: string format: date-time description: Date of last modification of the account name: type: string description: Name of the account paymentStatus: type: string description: The condition of the account, such as due, paid, in arrears. state: type: string description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.' accountBalance: type: array items: $ref: '#/definitions/AccountBalance' accountRelationship: type: array items: $ref: '#/definitions/AccountRelationship' billStructure: $ref: '#/definitions/BillStructure' contact: type: array items: $ref: '#/definitions/Contact' creditLimit: $ref: '#/definitions/Money' description: The maximum amount of money that may be charged on an account defaultPaymentMethod: $ref: '#/definitions/PaymentMethodRef' financialAccount: $ref: '#/definitions/FinancialAccountRef' paymentPlan: type: array items: $ref: '#/definitions/PaymentPlan' relatedParty: type: array items: $ref: '#/definitions/RelatedParty' minItems: 1 taxExemption: type: array items: $ref: '#/definitions/AccountTaxExemption' '@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 Error: description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx) type: object required: - code - reason properties: code: type: string description: Application relevant detail, defined in the API or a common list. reason: type: string description: Explanation of the reason for the error which can be shown to a client user. message: type: string description: More details and corrective actions related to the error which can be shown to a client user. status: type: string description: HTTP Error code extension referenceError: type: string format: uri description: URI of documentation describing the error. '@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. AccountBalance: type: object description: Balances linked to the account required: - amount - balanceType - validFor properties: balanceType: type: string description: 'Type of the balance : deposit balance, disputed balance, loyalty balance, receivable balance...' amount: $ref: '#/definitions/Money' description: Balance amount validFor: $ref: '#/definitions/TimePeriod' description: Balance validity period '@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 ContactMedium: type: object description: Indicates the contact medium that could be used to contact the party. properties: mediumType: type: string description: 'Type of the contact medium, such as: email address, telephone number, postal address' preferred: type: boolean description: If true, indicates that is the preferred contact medium characteristic: $ref: '#/definitions/MediumCharacteristic' description: Any additional characteristic(s) of this contact medium validFor: $ref: '#/definitions/TimePeriod' description: The time period that the contact medium is valid for '@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 BillingAccount_Update: type: object description: 'A party account used for billing purposes. It includes a description of the bill structure (frequency, presentation media, format and so on). It is a specialization of entity PartyAccount. Skipped properties: id,href,accountBalance' required: - name - relatedParty properties: accountType: type: string description: 'A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics. Note: for flexibility we use a String here but an implementation may use an enumeration with a limited list of valid values.' description: type: string description: Detailed description of the party account lastModified: type: string format: date-time description: Date of last modification of the account name: type: string description: Name of the account paymentStatus: type: string description: The condition of the account, such as due, paid, in arrears. state: type: string description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.' accountRelationship: type: array items: $ref: '#/definitions/AccountRelationship' billStructure: $ref: '#/definitions/BillStructure' contact: type: array items: $ref: '#/definitions/Contact' creditLimit: $ref: '#/definitions/Money' description: The maximum amount of money that may be charged on an account defaultPaymentMethod: $ref: '#/definitions/PaymentMethodRef' financialAccount: $ref: '#/definitions/FinancialAccountRef' paymentPlan: type: array items: $ref: '#/definitions/PaymentPlan' relatedParty: type: array items: $ref: '#/definitions/RelatedParty' minItems: 1 taxExemption: type: array items: $ref: '#/definitions/AccountTaxExemption' '@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 FinancialAccountRef: type: object description: AccountReceivable reference. An account of money owed by a party to another entity in exchange for goods or services that have been delivered or used. An account receivable aggregates the amounts of one or more party accounts (billing or settlement) owned by a given party. properties: id: type: string description: Unique identifier of the account href: type: string description: Unique reference of the account name: type: string description: Name of the account accountBalance: $ref: '#/definitions/AccountBalance' '@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 PaymentMethodRef: type: object description: PaymentMethod reference. A payment method defines a specific mean of payment (e.g direct debit). properties: id: type: string description: Unique identifier of the payment mean href: type: string description: Reference of the payment mean name: type: string description: Name of the payment mean '@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 TimePeriod: type: object description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both properties: endDateTime: type: string format: date-time description: End of the time period, using IETC-RFC-3339 format startDateTime: type: string format: date-time description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end MediumCharacteristic: type: object description: Describes the contact medium characteristics that could be used to contact a party (an individual or an organization) properties: city: type: string description: The city contactType: type: string description: 'The type of contact, for example: phone number such as mobile, fixed home, fixed office. postal address such as shipping instalation…' country: type: string description: The country emailAddress: type: string description: Full email address in standard format faxNumber: type: string description: The fax number of the contact phoneNumber: type: string description: The primary phone number of the contact postCode: type: string description: Postcode socialNetworkId: type: string description: Identifier as a member of a social network stateOrProvince: type: string description: State or province street1: type: string description: Describes the street street2: type: string description: Complementary street description '@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 BillFormatRefOrValue: type: object description: An attachment by value or by reference. required: - name - isRef properties: id: type: string description: Unique identifier of the bill format href: type: string description: Reference of the bill format description: type: string description: An explanatory text for this bill format isRef: default: true type: boolean name: type: string description: A short descriptive name '@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. BillingCycleSpecificationRefOrValue: type: object description: An attachment by value or by reference. required: - name - isRef properties: id: type: string description: Unique identifier of the billing cycle specification href: type: string description: Reference of the billing cycle specification billingDateShift: type: integer description: An offset of a billing/settlement date. The offset is expressed as number of days with regard to the start of the billing/settlement period. billingPeriod: type: string description: 'A billing time period. It can be recurring, for example: week, month, quarter of year, year .' chargeDateOffset: type: integer description: An offset of a date through which charges previously received by the billing system will appear on the bill. The offset is expressed as number of days with regard to the start of the BillingPeriod. creditDateOffset: type: integer description: An offset of a date through which credits previously received by the billing system will appear on the bill. The offset is expressed as number of days with regard to the start of the BillingPeriod. dateShift: type: integer description: An offset of a billing/settlement date. The offset is expressed as number of days with regard to the start of the billing/settlement period. description: type: string description: An explanation regarding this billing cycle specification frequency: type: string description: Frequency of the billing cycle (monthly for instance) isRef: default: true type: boolean mailingDateOffset: type: integer description: An offset of a customer bill mailing date. The offset is expressed as number of days with regard to the start of the BillingPeriod. name: type: string description: A short descriptive name paymentDueDateOffset: type: integer description: An offset of a payment due date. The offset is expressed as number of days with regard to the start of the BillingPeriod. validFor: $ref: '#/definitions/TimePeriod' description: The period for which the billing specification cycle is valid '@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. PaymentPlan: type: object description: Defines a plan for payment (when a party wants to spread his payments) properties: numberOfPayments: type: integer description: Number of payments used to spread the global payment paymentFrequency: type: string description: Frequency of the payments, such as monthly and bimonthly planType: type: string description: Type of payment plan priority: type: integer description: Priority of the payment plan status: type: string description: Status of the payment plan (effective, ineffective) paymentMethod: $ref: '#/definitions/PaymentMethodRef' totalAmount: $ref: '#/definitions/Money' description: Amount paid validFor: $ref: '#/definitions/TimePeriod' description: Validity period of the payment plan '@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 BillPresentationMediaRefOrValue: type: object description: An attachment by value or by reference. required: - name - isRef properties: id: type: string description: Unique identifier of the bill presentation media href: type: string description: Reference of the bill presentation media description: type: string description: An explanatory text describing this bill presentation media isRef: default: true type: boolean name: type: string description: A short descriptive name '@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. AccountTaxExemption: type: object description: Proof of freedom from taxes imposed by a taxing jurisdiction required: - issuingJurisdiction - validFor properties: certificateNumber: type: string description: Identifier of a document that shows proof of exemption from taxes for the taxing jurisdiction issuingJurisdiction: type: string description: Name of the taxing jurisdiction for which taxes are exempt reason: type: string description: Reason of the tax exemption validFor: $ref: '#/definitions/TimePeriod' description: Period for which the exemption is valid '@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 Money: type: object description: A base / value business entity used to represent money properties: unit: type: string description: Currency (ISO4217 norm uses 3 letters to define the currency) value: type: number format: float description: A positive floating point number Contact: type: object description: An individual or an organization used as a contact point for a given account and accessed via some contact medium. required: - contactType - validFor properties: contactName: type: string description: A displayable name for that contact contactType: type: string description: Type of contact (primary, secondary...) partyRoleType: type: string description: Identifies what kind of party role type is linked to the contact (a account manager...) contactMedium: type: array items: $ref: '#/definitions/ContactMedium' relatedParty: $ref: '#/definitions/RelatedParty' validFor: $ref: '#/definitions/TimePeriod' description: Validity period of that contact '@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 AccountRef: type: object description: Account reference. A account may be a party account or a financial account. properties: id: type: string description: Unique identifier of the account href: type: string description: Reference of the account description: type: string description: Detailed description of the account name: type: string description: Name of the 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 BillingAccount: type: object description: A party account used for billing purposes. It includes a description of the bill structure (frequency, presentation media, format and so on). It is a specialization of entity PartyAccount. required: - name - relatedParty properties: id: type: string description: Unique identifier of the account href: type: string description: Unique reference of the account accountType: type: string description: 'A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics. Note: for flexibility we use a String here but an implementation may use an enumeration with a limited list of valid values.' description: type: string description: Detailed description of the party account lastModified: type: string format: date-time description: Date of last modification of the account name: type: string description: Name of the account paymentStatus: type: string description: The condition of the account, such as due, paid, in arrears. state: type: string description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.' accountBalance: type: array items: $ref: '#/definitions/AccountBalance' accountRelationship: type: array items: $ref: '#/definitions/AccountRelationship' billStructure: $ref: '#/definitions/BillStructure' contact: type: array items: $ref: '#/definitions/Contact' creditLimit: $ref: '#/definitions/Money' description: The maximum amount of money that may be charged on an account defaultPaymentMethod: $ref: '#/definitions/PaymentMethodRef' financialAccount: $ref: '#/definitions/FinancialAccountRef' paymentPlan: type: array items: $ref: '#/definitions/PaymentPlan' relatedParty: type: array items: $ref: '#/definitions/RelatedParty' minItems: 1 taxExemption: type: array items: $ref: '#/definitions/AccountTaxExemption' '@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 BillStructure: type: object description: The structure of the bill for party accounts (billing or settlement). properties: cycleSpecification: $ref: '#/definitions/BillingCycleSpecificationRefOrValue' format: $ref: '#/definitions/BillFormatRefOrValue' presentationMedia: type: array items: $ref: '#/definitions/BillPresentationMediaRefOrValue' '@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 AccountRelationship: type: object description: Significant connection between accounts. For instance an aggregating account for a list of shop branches each having its own billing account. required: - relationshipType - validFor properties: relationshipType: type: string description: Type of relationship account: $ref: '#/definitions/AccountRef' validFor: $ref: '#/definitions/TimePeriod' description: Validity period of that relationship '@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 RelatedParty: type: object description: Related Entity reference. A related party defines party or party role linked to a specific entity. required: - '@referredType' - id - name properties: id: type: string description: Unique identifier of a related entity. href: type: string description: Reference of the related entity. name: type: string description: Name of the related entity. role: type: string description: Role played by the related party '@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.