Overview

The TMF666 API provides a standardized mechanism for billing account management, such as creation, update, retrieval, and deletion of billing accounts.
Using the TMF666 API you can perform the following operations on billing accounts.
- Retrieve the list of billing accounts from the system
- Get the billing account details
- Create a billing account
- Update an existing billing account
- Delete an existing billing account

In general, you can consider the various use cases listed based on the operation you want to perform.

Starting from the Winter ’27 release, only the Direct Access option is supported for this API.

Important

Assumptions

It is assumed that you have completed the following.

Enabling Access to Industry APIs
Ensuring that the required licenses are enabled. See TMF666 v5 Account Management API.

NOTE:

For mandatory fields and resource mappings, see TMF666 v5 Resource Mappings.

Use Cases

I want to	Request Type	Example URL
Retrieve and display details of a particular billing account.	GET by ID	{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID} NOTE: For an invalid ID, you receive HTTP 404 error.
Based on the provided field values, retrieve and display details of billing accounts.	GET with Fields	{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?fields=name NOTE: The requested fields are part of the output if they have a value.
List all the billing accounts present in the system.	GET List	{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount
List billing accounts present in the system based on the filter applied.	GET List with Filtering	{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?name=TMF666 Account NOTE: The requested fields are part of the output if they have a value.
List billing accounts, limit the number of records to a specified limit, and start the results from the page specified by offset.	GET List by limit and offset	{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?offset=4&pageLimit=1&pageinfo=true
Create a new billing account by providing the required details.	POST	{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount NOTE: A new billing account is created based on the values mentioned for the mandatory fields.
Update details of a particular billing account.	PATCH	{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}
Delete a billing account.	DELETE	{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID} NOTE: DELETE is a soft delete. The account state is set to Inactive.

GET by ID

Consider you want to retrieve details of a particular billing account.

Sample URL

{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}

Sample Response

1{
2    "id": "15ixx0000004C92AAE",
3    "href": "/connect/comms/accountmanagement/v5/billingaccount/15ixx0000004C92AAE",
4    "name": "UpdatedAcct001",
5    "state": "Active",
6    "accountType": "Residential",
7    "lastUpdate": "2026-04-09T05:25:10.000Z",
8    "billStructure": {
9        "format": {
10            "name": "Detailed",
11            "@type": "BillFormat"
12        },
13        "presentationMedia": [
14            {
15                "name": "Email",
16                "@type": "BillPresentationMedia"
17            }
18        ],
19        "cycleSpecification": {
20            "frequency": "Monthly",
21            "@type": "BillingCycleSpecification"
22        },
23        "@type": "BillStructure"
24    },
25    "taxExemption": [
26        {
27            "certificateNumber": "TAX-EXEMPT-001",
28            "validFor": {
29                "startDateTime": "2025-01-01T00:00:00.000Z",
30                "endDateTime": "2026-12-31T00:00:00.000Z"
31            },
32            "reason": "Government",
33            "@type": "TaxExemption"
34        }
35    ],
36    "relatedParty": [
37        {
38            "role": "Financially Responsible Party",
39            "partyOrPartyRole": {
40                "id": "001xx000003HJdrAAG",
41                "href": "/services/data/v68.0/sobjects/Account/001xx000003HJdrAAG",
42                "name": "Acme Corp",
43                "@type": "PartyRef",
44                "@referredType": "Organization"
45            },
46            "@type": "RelatedPartyRefOrRelatedPartyRoleRef"
47        }
48    ],
49    "contact": [
50        {
51            "id": "003xx000004WpZwAAK",
52            "contactName": "John Doe",
53            "contactType": "Bill To",
54            "validFor": {
55                "endDateTime": "2099-12-31T00:00:00.000Z"
56            },
57            "contactMedium": [
58                {
59                    "id": "15ixx0000004C92AAE-cm-1",
60                    "contactType": "billing email",
61                    "preferred": true,
62                    "emailAddress": "billing@acme.com",
63                    "@type": "EmailContactMedium"
64                },
65                {
66                    "id": "15ixx0000004C92AAE-cm-2",
67                    "contactType": "billing address",
68                    "preferred": true,
69                    "city": "San Francisco",
70                    "country": "US",
71                    "postCode": "94105",
72                    "stateOrProvince": "CA",
73                    "street1": "123 Main St",
74                    "@type": "GeographicAddressContactMedium"
75                }
76            ],
77            "@type": "Contact"
78        }
79    ],
80    "@type": "BillingAccount"
81}

GET with Fields

Consider you want to retrieve billing accounts and return only these fields in the output.

id
name

Sample URL

{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?fields=name

Sample Response

1[
2  {
3    "@type": "BillingAccount",
4    "name": "UpdatedAcct001",
5    "id": "15ixx0000004C92AAE",
6    "href": "/connect/comms/accountmanagement/v5/billingaccount/15ixx0000004C92AAE"
7  },
8  {
9    "@type": "BillingAccount",
10    "name": "Home Account",
11    "id": "15ixx0000004CAeAAM",
12    "href": "/connect/comms/accountmanagement/v5/billingaccount/15ixx0000004CAeAAM"
13  }
14]

GET List

Consider there are multiple billing accounts in the system and you want to list all of them.

Sample URL

{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount

GET List with Filtering

Consider you want to retrieve billing accounts with applied filter values. Supported filters include name and id.

Sample URL

{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?name=TMF666 Account

GET List by limit and offset

Consider you want to retrieve a list of billing accounts, limit the number of records, and start the results from the specified offset.

offset is the number of records to skip. Minimum value is 0.
pageLimit is the page size. Minimum value is 1 and maximum value is 2000.
Pagination is supported for up to 100,000 records (offset + pageLimit must be less than or equal to 100,000).

Sample URL

{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?offset=4&pageLimit=1&pageinfo=true

POST

Consider you want to create a new billing account. name and relatedParty are mandatory.

Sample URL

{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount

Sample Request

1{
2  "@type": "BillingAccount",
3  "name": "New Account",
4  "relatedParty": [
5    {
6      "role": "service provider",
7      "@type": "RelatedPartyRefOrRelatedPartyRoleRef",
8      "partyOrPartyRole": {
9        "id": "001xx000003HP8BAAW"
10      }
11    }
12  ]
13}

Sample Response

1{
2  "id": "15ixx0000004N4SAAU",
3  "href": "/connect/comms/accountmanagement/v5/billingaccount/15ixx0000004N4SAAU",
4  "name": "New Account",
5  "state": "Active",
6  "lastUpdate": "2026-04-26T15:51:29.000Z",
7  "relatedParty": [
8    {
9      "role": "Financially Responsible Party",
10      "partyOrPartyRole": {
11        "id": "001xx000003HP8BAAW",
12        "href": "/services/data/v68.0/sobjects/Account/001xx000003HP8BAAW",
13        "name": "Test Acme Corp",
14        "@type": "PartyRef",
15        "@referredType": "Organization"
16      },
17      "@type": "RelatedPartyRefOrRelatedPartyRoleRef"
18    }
19  ],
20  "@type": "BillingAccount"
21}

PATCH

Consider you want to update details of a particular billing account.

Patchable attributes include name, state, accountType, bill structure fields (format, presentationMedia, cycleSpecification.frequency), and tax exemption fields (certificateNumber, start and end dates, and reason).

These attributes are not patchable: id, href, lastUpdate, relatedParty, contact, contact.contactMedium, and defaultPaymentMethod.

Sample URL

{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}

Sample Request

1{
2  "@type": "BillingAccount",
3  "name": "Billing Account Updated 2.0",
4  "state": "Active",
5  "accountType": "Commercial",
6  "billStructure": {
7    "@type": "BillStructure",
8    "presentationMedia": [
9      {
10        "@type": "BillPresentationMedia",
11        "name": "EBill"
12      }
13    ],
14    "format": {
15      "@type": "BillFormat",
16      "name": "Summary Bill"
17    },
18    "cycleSpecification": {
19      "@type": "BillingCycleSpecification",
20      "frequency": "Monthly"
21    }
22  },
23  "taxExemption": [
24    {
25      "certificateNumber": "TAX-12345",
26      "reason": "Lower Income Group",
27      "startDateTime": "2025-01-01T00:00:00.000Z",
28      "endDateTime": "2027-12-31T00:00:00.000Z"
29    }
30  ]
31}

DELETE

DELETE is a soft delete. The API sets the billing account state to Inactive. The record is not physically deleted.

Sample URL

{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}

Sample Request

No request body.

Sample Response

Status code 204 with no response body.