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

Get Customer Bills

get

/customerBill

Gets the customer bills that match the query criteria.

Request

Query Parameters
  • The type of object to return.
    Examples

  • Retrieves the customer bills with an amount due that matches the specified value.
    Examples

  • Retrieves the customer bills with an amount due that is greater than the specified value.
    Examples

  • Retrieves the customer bills with an amount due that is greater than or equal to the specified value.
    Examples

  • Retrieves the customer bills with an amount due value that is less than the specified value.
    Examples

  • Retrieves the customer bills with an amount due that is less than or equal to the specified value.
    Examples

  • Retrieves the customer bills with a billDate that matches the specified dateTime.
    Examples

  • Retrieves the customer bills with a billDate that is greater than the specified dateTime.
    Examples

  • Retrieves the customer bills with a billDate that is greater than or equal to the specified dateTime.
    Examples

  • Retrieves the customer bills with a billDate that is less than the specified dateTime.
    Examples

  • Retrieves the customer bills with a billDate that is less than or equal to the specified dateTime.
    Examples

  • Retrieves customer bills by bill number. To retrieve the bills that are in progress, enter bill in progress all lowercase.
    Examples

  • Retrieves customer bills that match the specified bill number. Use the URL-encoded wild-card character %25 to replace one or more characters.
    Examples

  • Retrieves customer bills for the specified account ID or account number.
    Examples

  • Retrieves the customer bills with a billing period end date time that matches the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period end date time that is greater than the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period end date time that is greater than or equal to the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period end date time that is less than the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period end date time that is less than or equal to the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period start date time that matches the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period start date time that is greater than the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period start date that is greater than or equal to the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period start date time that is less than the specified dateTime.
    Examples

  • Retrieves the customer bills with a billing period start date time that is less than or equal to the specified dateTime.
    Examples

  • The list of comma-separated fields to return in the response.
    Examples

  • Retrieves customer bills for the specified bill ID.
    Examples

  • Retrieves the customer bills whose lastUpdate matches the specified dateTime.
    Examples

  • Retrieves the customer bills whose lastUpdate is greater than the specified dateTime.
    Examples

  • Retrieves the customer bills whose lastUpdate is less than the specified dateTime.
    Examples

  • Retrieves customer bills whose lastUpdate is less than the specified dateTime.
    Examples

  • Retrieves the customer bills whose lastUpdate is less than or equal to the specified dateTime.
    Examples

  • The maximum number of results to return.
    Examples

  • The number of results to offset the response by.
    Examples

  • Retrieves the customer bills with a paymentDueDate that matches the specified dateTime.
    Examples

  • Retrieves the customer bills with a paymentDueDate that is greater than the specified dateTime.
    Examples

  • Retrieves the customer bills with a paymentDueDate that is greater than or equal to the specified dateTime.
    Examples

  • Retrieves the customer bills with a paymentDueDate that is less than the specified dateTime.
    Examples

  • Retrieves the customer bills with a paymentDueDate that is less than or equal to the specified dateTime.
    Examples

  • Retrieves the customer bills with a remaining amount that matches the specified value.
    Examples

  • Retrieves the customer bills with a remaining amount that is greater than the specified value.
    Examples

  • Retrieves the customer bills with a remaining amount that is greater than or equal to the specified value.
    Examples

  • Retrieves the customer bills with a wild card in the remaining amount value. Use the URL-encoded wild-card character %25 to replace one or more characters.
    Examples

  • Retrieves the customer bills with a remaining amount that is less than the specified value.
    Examples

  • Retrieves the customer bills with a remaining amount that is less than or equal to the specified value.
    Examples

  • The state of the bill, such as new, partiallyPaid, settled, or inProgress.
    Examples

    Allowed Values: [ "new", "partiallyPaid", "settled", "inProgress" ]

There's no request body for this operation.

Back to Top

Response

Supported Media Types

200 Response

The customer bills were retrieved successfully.
Headers
Body ()
Root Schema : schema
Type: array
Show Source
Nested 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: Get In Progress Customer Bills by Payment Due Date

The following example shows how to get bills by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

The request uses query parameters to show a maximum of two results, limited to bills in progress that have a payment due date later than or equal to June 1, 2025.

curl -X GET 'http://host:port/brm/customerBillManagement/version/customerBill?limit=2&state=inProgress&paymentDueDate.gte=2025-06-01T01:05:29-07:00'

Example of the Response Body

The following example shows the contents 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": "John Miller",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": "billingAccount"
      },
      "billingPeriod": {
         "endDateTime": null,
         "startDateTime": "2025-05-02T00:00:00-07:00"
      },
      "financialAccount": {
         "id": "0.0.0.1+-account+107117",
         "href": null,
         "name": "John Miller",
         "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": "inProgress",
      "taxExcludedAmount": {
         "unit": "EUR",
         "value": 86.0
      },
      "taxIncludedAmount": {
         "unit": "EUR",
         "value": 90.0
      },
      "taxItem": null,
      "@baseType": "CustomerBill",
      "@schemaLocation": null,
      "@type": "CustomerBill"
    },
    {
      "id": "0.0.0.1+-bill+103581",
      "href": "http://host:port/brm/customerBillManagement/version/customerBill/0.0.0.1+-bill+103581",
      "billDate": null,
      "billNo": "bill in progress",
      "category": "0",
      "lastUpdate": "2025-05-02T00:23:54-07:00",
      "nextBillDate": "2025-06-02T00:00:00-07:00",
      "paymentDueDate": "2025-10-12T01:05:29-07:00",
      "runType": "onCycle",
      "amountDue": {
         "unit": "USD",
         "value": 100.0
      },
      "appliedPayment": null,
      "billDocument": null,
      "billingAccount": {
         "id": "0.0.0.1+-account+104221",
         "href": null,
         "name": "John Miller",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": "billingAccount"
      },
      "billingPeriod": {
         "endDateTime": null,
         "startDateTime": "2025-05-02T00:00:00-07:00"
      },
      "financialAccount": {
         "id": "0.0.0.1+-account+104221",
         "href": null,
         "name": "John Miller",
         "accountBalance": null,
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": "financialAccount"
      },
      "paymentMethod": {
         "id": "0.0.0.1+-payinfo-invoice+106269",
         "href": null,
         "name": "Invoice1",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": null
      },
      "relatedParty": null,
      "remainingAmount": {
         "unit": "USD",
         "value": 0.0
      },
      "state": "inProgress",
      "taxExcludedAmount": {
         "unit": "USD",
         "value": 93.75
      },
      "taxIncludedAmount": {
         "unit": "USD",
         "value": 100.0
      },
      "taxItem": null,
      "@baseType": "CustomerBill",
      "@schemaLocation": null,
      "@type": "CustomerBill"
   }
]

Example 2: Get Bills Associated with an Account Number

The following example shows how to get bills by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

This request uses query parameters to show all bills associated with a specified account number.

curl -X GET 'http://host:port/brm/customerBillManagement/version/customerBill?limit=2&billingAccount.id=Account-1234'

Example of the Response Body

The following example shows the contents 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": "Account-1234",
         "href": null,
         "name": "John Miller",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": "billingAccount"
      },
      "billingPeriod": {
         "endDateTime": null,
         "startDateTime": "2025-05-02T00:00:00-07:00"
      },
      "financialAccount": {
         "id": "0.0.0.1+-account+107117",
         "href": null,
         "name": "John Miller",
         "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": "inProgress",
      "taxExcludedAmount": {
         "unit": "EUR",
         "value": 86.0
      },
      "taxIncludedAmount": {
         "unit": "EUR",
         "value": 90.0
      },
      "taxItem": null,
      "@baseType": "CustomerBill",
      "@schemaLocation": null,
      "@type": "CustomerBill"
    },
    {
      "id": "0.0.0.1+-bill+103581",
      "href": "http://host:port/brm/customerBillManagement/version/customerBill/0.0.0.1+-bill+103581",
      "billDate": null,
      "billNo": "bill in progress",
      "category": "0",
      "lastUpdate": "2025-05-02T00:23:54-07:00",
      "nextBillDate": "2025-06-02T00:00:00-07:00",
      "paymentDueDate": "2025-10-12T01:05:29-07:00",
      "runType": "onCycle",
      "amountDue": {
         "unit": "USD",
         "value": 100.0
      },
      "appliedPayment": null,
      "billDocument": null,
      "billingAccount": {
         "id": "Account-1234",
         "href": null,
         "name": "John Miller",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": "billingAccount"
      },
      "billingPeriod": {
         "endDateTime": null,
         "startDateTime": "2025-05-02T00:00:00-07:00"
      },
      "financialAccount": {
         "id": "0.0.0.1+-account+104221",
         "href": null,
         "name": "John Miller",
         "accountBalance": null,
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": "financialAccount"
      },
      "paymentMethod": {
         "id": "0.0.0.1+-payinfo-invoice+106269",
         "href": null,
         "name": "Invoice1",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null,
         "@referredType": null
      },
      "relatedParty": null,
      "remainingAmount": {
         "unit": "USD",
         "value": 0.0
      },
      "state": "inProgress",
      "taxExcludedAmount": {
         "unit": "USD",
         "value": 93.75
      },
      "taxIncludedAmount": {
         "unit": "USD",
         "value": 100.0
      },
      "taxItem": null,
      "@baseType": "CustomerBill",
      "@schemaLocation": null,
      "@type": "CustomerBill"
   }
]
Back to Top