1. REST Services Manager API for Billing and Revenue Management
  2. Tasks
  3. Customer Bill Management
  4. Customer Bill

Update a Customer Bill

patch

/customerBill/{id}

Updates a customer bill. You can update the value of the bill's state property from InProgress to OnHold, or from OnHold to InProgress.

Request

Path Parameters
Supported Media Types
Request Body - application/json;charset=utf-8 ()
Root Schema : Customer Bill Update
Type: object
Title: Customer Bill Update
A customer bill, used in the bill update request when changing the bill's state.
Show Source
  • Title: Base Type
    The object's superclass.
  • Title: Schema Location
    A URI to a JSON schema file that defines additional attributes and relationships.
  • Title: Type
    The object's subclass.
  • Title: State Value
    Allowed Values: [ "new", "partiallyPaid", "settled", "onHold", "inProgress" ]
    The possible values for a bill's state: new, partiallyPaid, settled, onHold, and inProgress.
Back to Top

Response

Supported Media Types

200 Response

The customer bill was updated successfully.
Body ()
Root Schema : Customer Bill
Type: object
Title: Customer Bill
A customer bill, also called an invoice.
Show Source
Nested Schema : Money
Type: object
The base / value business entity used to represent money.
Show Source
  • The currency (ISO4217 norm uses 3 letters to define the currency).
  • The signed floating point number, the meaning of the sign is according to the context of the API that uses this Data type
Nested Schema : appliedPayment
Type: array
The payments applied to the bill.
Show Source
Nested Schema : billDocument
Type: array
A document attached to the bill.
Show Source
  • Discriminator: @type
    Discriminator: { "propertyName":"@type", "mapping":{ "Attachment":"#/components/schemas/Attachment", "AttachmentRef":"#/components/schemas/AttachmentRef" } }
    The polymorphic attributes @type, @schemaLocation, and @referredType are related to the Attachment entity and not the AttachmentRefOrValue class itself.
Nested Schema : Billing Account Ref
Type: object
Title: Billing Account Ref
A billing account is a detailed description of a bill structure.
Show Source
Nested Schema : TimePeriod
Type: object
The period of time, either as a deadline (endDateTime only) a startDateTime only, or both.
Show Source
Nested Schema : Financial Account Ref
Type: object
Title: Financial Account Ref
A financial account reference.
Show Source
Nested Schema : PaymentMethodRef
Type: object
The PaymentMethod reference. A payment method defines a specific means of payment, such as direct debit.
Match All
The PaymentMethod reference. A payment method defines a specific means of payment, such as direct debit.
Show Source
Nested Schema : relatedParty
Type: array
The parties related to the bill.
Show Source
Nested Schema : taxItem
Type: array
The taxes on the bill.
Show Source
Nested Schema : Applied Payment
Type: object
Title: Applied Payment
A payment that can be assigned to a bill.
Show Source
Nested Schema : PaymentRef
Type: object
A payment received at order time.
Show Source
Nested Schema : Discriminator: @type
Type: object
Discriminator: @type

Discriminator Values

The polymorphic attributes @type, @schemaLocation, and @referredType are related to the Attachment entity and not the AttachmentRefOrValue class itself.
Match One Schema
Show Source
Nested Schema : Attachment
Match All
The complementary description of an element (for instance a product) through video, pictures, etc.
Show Source
Nested Schema : AttachmentRef
Match All
The attachment reference. An attachment complements the description of an element (for instance a product) through video, pictures.
Show Source
Nested Schema : Entity
Type: object
The Base entity schema for use in TMForum Open-APIs Property.
Match All
The Base entity schema for use in TMForum Open-APIs Property.
The Base entity schema for use in TMForum Open-APIs Property.
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Addressable
    The base schema for adressable entities.
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Addressable
Type: object
The base schema for adressable entities.
Show Source
Nested Schema : Attachment-allOf[1]
Type: object
The complementary description of an element (for instance a product) through video, pictures, etc.
Show Source
Nested Schema : Quantity
Type: object
The amount in a given unit.
Show Source
Nested Schema : EntityRef
Match All
The entity reference schema to be use for all entityRef class.
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Addressable
    The base schema for adressable entities.
  • EntityRef-allOf[2]
    The entity reference schema to be use for all entityRef class.
Nested Schema : EntityRef-allOf[2]
Type: object
The entity reference schema to be use for all entityRef class.
Show Source
Nested Schema : AttachmentRef-allOf[1]
Type: object
The attachment reference. An attachment complements the description of an element (for instance a product) through video, pictures.
Show Source
Nested Schema : accountBalance
Type: array
The account's balances.
Show Source
Nested Schema : AccountBalance
Match All
The balances linked to the account.
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • AccountBalance-allOf[1]
    The balances linked to the account.
Nested Schema : AccountBalance-allOf[1]
Type: object
The balances linked to the account.
Show Source
Nested Schema : Related Party Ref
Type: object
Title: Related Party Ref
A reference to the party related to an object.
Show Source
Nested Schema : State Values
Type: object
Title: State Values
A tax item.
Show Source

400 Response

The request isn't valid.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

401 Response

The client doesn't have the correct privileges.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

403 Response

The request wasn't authorized.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

404 Response

The requested resource couldn't be found.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

405 Response

This method is not allowed.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

409 Response

The request could not be processed due to the conflict with the existing state of the resource.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

500 Response

The system encountered an internal error.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source
Back to Top

Examples

Example 1: Update a Customer Bill by Billing POID

The following example shows how to update the state of a customer bill by submitting a PATCH request on the REST resource using cURL. For more information about cURL, see Use cURL.

The -d option specifies the file to attach as the request body. 

curl -X PATCH 'http://host:port/brm/customerBillManagement/version/customerBill/0.0.0.1+-bill+106861' -d @billUpdate.json

Example of Request Body

The following is an example of the contents of the billUpdate.json file sent as the request body. You can only use the PATCH method to update the bill state from InProgress to OnHold, or from OnHold to InProgress. 

{    
   "state": "OnHold",
   "@baseType": "CustomerBill",
    "@schemaLocation": null,
    "@type": "CustomerBill"
}

Example of Response Body

The following is an example of the response body in JSON format.

{
   "id": "0.0.0.1+-bill+106861",
   "href": "http://host:port/brm/customerBillManagement/version/customerBill/0.0.0.1+-bill+106861",
   "billDate": null,
   "billNo": "bill in progress",
   "category": "0",
   "lastUpdate": "2025-05-02T01:14:13-07:00",
   "nextBillDate": "2025-06-13T00:00:00-07:00",
   "paymentDueDate": "2025-08-01T01:05:29-07:00",
   "runType": "onCycle",
   "amountDue": {
      "unit": "EUR",
      "value": 90.0
   },
   "appliedPayment": null,
   "billDocument": null,
   "billingAccount": {
      "id": "0.0.0.1+-account+107117",
      "href": null,
      "name": "Tanya Levy",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null,
      "@referredType": "billingAccount"
   },
   "billingPeriod": {
      "endDateTime": null,
      "startDateTime": "2024-05-02T00:00:00-07:00"
   },
   "financialAccount": {
      "id": "0.0.0.1+-account+107117",
      "href": null,
      "name": "Tanya Levy",
      "accountBalance": null,
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null,
      "@referredType": "financialAccount"
   },
   "paymentMethod": {
      "id": "0.0.0.1+-payinfo-invoice+109165",
      "href": null,
      "name": "4243324",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null,
      "@referredType": null
   },
   "relatedParty": null,
   "remainingAmount": {
      "unit": "EUR",
      "value": 90.0
   },
   "state": "OnHold",
   "taxExcludedAmount": {
      "unit": "EUR",
      "value": 86.0
   },
   "taxIncludedAmount": {
      "unit": "EUR",
      "value": 90.0
   },
   "taxItem": null,
   "@baseType": "CustomerBill",
   "@schemaLocation": null,
   "@type": "CustomerBill"
}

Example 2: Update a Customer Bill by Bill Number

The following example shows how to update the state of a customer bill by submitting a PATCH request on the REST resource using cURL. For more information about cURL, see Use cURL.

The -d option specifies the file to attach as the request body. 

curl -X PATCH 'http://host:port/brm/customerBillManagement/version/customerBill/Bill-123' -d @billUpdate.json

Example of Request Body

The following is an example of the contents of the billUpdate.json file sent as the request body. You can only use the PATCH method to update the bill state from InProgress to OnHold, and from OnHold to InProgress. 

{    
   "state": "InProgress",
   "@baseType": "CustomerBill",
    "@schemaLocation": null,
    "@type": "CustomerBill"
}

Example of Response Body

The following is an example of the response body in JSON format.

{
   "id": "Bill-123",
   "href": "http://host:port/brm/customerBillManagement/version/customerBill/Bill-123",
   "billDate": null,
   "billNo": "Bill-123",
   "category": "0",
   "lastUpdate": "2025-05-02T01:14:13-07:00",
   "nextBillDate": "2025-06-13T00:00:00-07:00",
   "paymentDueDate": "2025-08-01T01:05:29-07:00",
   "runType": "onCycle",
   "amountDue": {
      "unit": "USD",
      "value": 146.0
   },
   "appliedPayment": null,
   "billDocument": null,
   "billingAccount": {
      "id": "0.0.0.1+-account+107117",
      "href": null,
      "name": "Mary Carter",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null,
      "@referredType": "billingAccount"
   },
   "billingPeriod": {
      "endDateTime": null,
      "startDateTime": "2024-05-02T00:00:00-07:00"
   },
   "financialAccount": {
      "id": "0.0.0.1+-account+107117",
      "href": null,
      "name": "Mary Carter",
      "accountBalance": null,
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null,
      "@referredType": "financialAccount"
   },
   "paymentMethod": {
      "id": "0.0.0.1+-payinfo-invoice+109165",
      "href": null,
      "name": "4243324",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null,
      "@referredType": null
   },
   "relatedParty": null,
   "remainingAmount": {
      "unit": "USD",
      "value": 50.0
   },
   "state": "InProgress",
   "taxExcludedAmount": {
      "unit": "USD",
      "value": 15.0
   },
   "taxIncludedAmount": {
      "unit": "USD",
      "value": 12.0
   },
   "taxItem": null,
   "@baseType": "CustomerBill",
   "@schemaLocation": null,
   "@type": "CustomerBill"
}
Back to Top