--- schema_version: "1" id: a080499fccfc424034ec3470c267680a1d18dcb82054f2db8e65055d553ed580 title: Integrations API collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/energy/references/generated-api-specs/energyapi.md canonical_url: https://developer.salesforce.com/docs/industries/energy/references/energyapi source_site: developer.salesforce.com content_type: documentation content_hash: bb38d58988b3c8cdcbd766ac64a6f6e904dcc2f82ca3b8275b833e8582a1fc9e products: - Energy and Utilities Cloud API - Industries Integrations --- Integrations API # Integrations API Use the Energy and Utilities Integrations APIs to integrate the Energy and Utilities Cloud apps with external billing systems. **Version:** v1 Protocols: HTTPS. ## Operations ### POST Create an account `POST /accounts` Creates a customer's account in the billing system, based on the customer interaction via Salesforce. #### Request body Media type: `application/json`. Schema: `object`. Account details. * `billingCountry` (_string_) Country of the billing address. Example: `USA`. * `billingPostalCode` (_number | string_) Postal code of the billing address. _Example_ ``` 10003 ``` One of: `number`, `string`. _Example_ ``` 10003 ``` * `mailingStreetAddress` (_string_) Street of the mailing address. Example: `Main St`. * `mailingCity` (_string_) City of the mailing address. Example: `New York`. * `accountName` (_string_, required) Name of the account. Example: `Northern Region`. * `externalCustomerId` (_string_) The billing system's unique identifier for the customer. Example: `0015f000004AagjZZZ`. * `mailingState` (_string_) State of the mailing address. Example: `New York`. * `company` (_string_) Company of the account. Example: `Green Energy`. * `mailingPostalCode` (_number | string_) Postal code of the mailing address. _Example_ ``` 10003 ``` One of: `number`, `string`. _Example_ ``` 10003 ``` * `billDeliveryMethod` (_string_) Bill delivery method, such as paper, electronic, or email. Example: `Paper`. * `email` (_string_, required) Email address of the account. Example: `example@example.com`. * `accountId` (_string_, required) Unique identifier for the account in Salesforce. Example: `0015f000004jXxjZZZ`. * `IsAutopayEnabled` (_boolean_) Whether the customer has opted for automatic payment (true) or not (false). Example: `true`. * `billingState` (_string_) State of the billing address. Example: `New York`. * `requestDateTime` (_datetime (rfc3339)_, required) The timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-01-25T12:35:28.689Z`. * `phoneAreaCode` (_string_) Area code of the account phone number. Example: `+1`. * `billingStreetAddress` (_string_) Street of the billing address. Example: `Main St`. * `fax` (_string_) Fax number of the account. Example: `555-123-4567`. * `phone` (_string_) Phone number of the account. Example: `5551234567`. * `billingHouseNumber` (_string_) House number of the account per the billing address. Example: `B-507`. * `mobilePhone` (_string_) Mobile phone number of the account. Example: `5551234567`. * `mobilePhoneAreaCode` (_string_) Area code of the account mobile phone number. Example: `+1`. * `billingFrequency` (_string_) Frequency of billing, such as monthly or quarterly. Example: `Monthly`. * `billingCity` (_string_) City of the billing address. Example: `New York`. * `mailingHouseNumber` (_string_) House number of the mailing address. Example: `B-607`. * `status` (_string_) Status of the account. Example: `Active`. * `mailingCountry` (_string_) Country of the mailing address. Example: `USA`. #### Responses * **201** Media type: `application/json`. Schema: `object`. * `externalAccountId` (_string_, required) The external account that the bill is tagged to. Example: `001RN000002rEkrYAE`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### PUT Update account details `PUT /accounts/{externalAccountId}` Updates a customer's account in the billing system, based on the customer interaction via Salesforce. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `0015f00000FpRVuAAK`. #### Request body Media type: `application/json`. Schema: `object`. Account details. * `billingCountry` (_string_) Country of the billing address. Example: `USA`. * `billingPostalCode` (_number | string_) Postal code of the billing address. _Example_ ``` 10003 ``` One of: `number`, `string`. _Example_ ``` 10003 ``` * `mailingStreetAddress` (_string_) Street of the mailing address. Example: `Main St`. * `mailingCity` (_string_) City of the mailing address. Example: `New York`. * `accountName` (_string_, required) Name of the account. Example: `Northern Region`. * `externalCustomerId` (_string_, required) The billing system's unique identifier for the customer. Example: `0015f000004AagjZZZ`. * `mailingState` (_string_) State of the mailing address. Example: `New York`. * `company` (_string_) Company of the account. Example: `Green Energy`. * `mailingPostalCode` (_number | string_) Postal code of the mailing address. _Example_ ``` 10003 ``` One of: `number`, `string`. _Example_ ``` 10003 ``` * `billDeliveryMethod` (_string_) Bill delivery method, such as paper, electronic, or email. Example: `Paper`. * `email` (_string_, required) Email address of the account. Example: `example@example.com`. * `accountId` (_string_, required) Unique identifier for the account in Salesforce. Example: `0015f000004jXxjZZZ`. * `IsAutopayEnabled` (_boolean_) Whether the customer has opted for automatic payment (true) or not (false). Example: `true`. * `billingState` (_string_) State of the billing address. Example: `New York`. * `requestDateTime` (_datetime (rfc3339)_, required) The timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-01-25T12:35:28.689Z`. * `phoneAreaCode` (_string_) Area code of the account phone number. Example: `+1`. * `billingStreetAddress` (_string_) Street of the billing address. Example: `Main St`. * `fax` (_string_) Fax number of the account. Example: `555-123-4567`. * `phone` (_string_) Phone number of the account. Example: `5551234567`. * `billingHouseNumber` (_string_) House number of the account per the billing address. Example: `B-507`. * `mobilePhone` (_string_) Mobile phone number of the account. Example: `5551234567`. * `mobilePhoneAreaCode` (_string_) Area code of the account mobile phone number. Example: `+1`. * `billingFrequency` (_string_) Frequency of billing, such as monthly or quarterly. Example: `Monthly`. * `billingCity` (_string_) City of the billing address. Example: `New York`. * `mailingHouseNumber` (_string_) House number of the mailing address. Example: `B-607`. * `status` (_string_) Status of the account. Example: `Active`. * `mailingCountry` (_string_) Country of the mailing address. Example: `USA`. #### Responses * **200** Media type: `application/json`. Schema: `object`. * `externalAccountId` (_string_, required) The external account that the bill is tagged to. Example: `0015f00000FpRVuAAK`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Get customer financial adjustments `GET /accounts/{externalAccountId}/financialAdjustments` Retrieves a list of financial adjustments linked to an account in the billing system. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `AC36789`. #### Responses * **200** Media type: `application/json`. Schema: `object`. The collection of financial adjustments from the account. * `financialAdjustments` (_array of object_, required) Each item: Financial adjustments for the account. * `externalAdjustmentId` (_string_, required) Reference to the unique external adjustment identifier. Example: `0015f00000XpRVuCDE`. * `adjustmentDate` (_date-only_, required) Date of request for the adjustment. The current date is the default value. Example: `2024-01-28`. * `adjustmentReason` (_string_) Reason for requesting the adjustment, such as high bill, goodwill, or compensation. Example: `Compensation`. * `adjustmentAmount` (_number (double)_, required) Total positive or negative bill adjustment amount, including applicable taxes. Example: `123.43`. * `adjustmentTaxAmount` (_number (double)_) Tax amount of the financial adjustment, if applicable. Example: `1234.32`. * `currencyCode` (_string_, required) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `adjustmentType` (_string_) Type of financial adjustment. Example: `Credit`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Retrieve account balance `GET /accounts/{externalAccountId}/balance` Retrieves the current balance, latest bill, and payment amounts for a specified account from the given date. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `0015f00000FpRVuAAK`. * `balanceDate` (query, date-only) The date when the balance is requested. If the balanceDate property isn’t specified, the default value is the current date. Example: `2022-01-25`. #### Responses * **200** Media type: `application/json`. Schema: `accountBalance`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Retrieve bills `GET /accounts/{externalAccountId}/bills` Retrieves a list of bills for the specified account. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `0015f00000GoIVuAAN`. * `startDate` (query, date-only) Optional. If specified, it defines the billing start date. Example: `2022-01-24`. * `endDate` (query, date-only) Optional. If specified, it defines the billing end date. If not specified, the current date is used. Example: `2022-01-24`. * `numberOfBills` (query, integer (int)) The number of bills to retrieve. If specified, it overrides the startDate property to retrieve the specified number of bills. Example: `7`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves a collection of bills. * `bills` (_array of object_, required) Each item: Bill details. * `billId` (_string_, required) Unique reference to a single bill in the billing system. Example: `10239474748590`. * `billDate` (_date-only_, required) Date when the bill is generated, which is the end date of the billing period. Example: `2022-01-24`. * `billAmount` (_number (double)_, required) Total bill amount. Example: `1000`. * `currencyCode` (_string_, required) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `billDueDate` (_date-only_, required) Due date to pay the bill. Example: `2022-01-24`. * `billUrl` (_string_, required) A link to the copy of the bill. Example: `https://commerce-commerce-43841.lightning.force.com/resource/dummy_pdf`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Retrieve bill details `GET /accounts/{externalAccountId}/bills/{externalBillId}` Retrieves a list of the bill line items for the specified bill ID. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `0015f00000GoIVuAAN`. * `externalBillId` (path, string, required) The billing system’s unique identifier of a single bill. Example: `14567`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves a collection of the bill line items. * `billLineItems` (_array of object_, required) Each item: Details of the bill line item. * `lineNumber` (_string_, required) Unique reference to a line item within a bill in the billing system. Example: `0065f000009YXE9AAO`. * `lineItemDescription` (_string_, required) Text displayed for the line item. Example: `Line item description`. * `usageQty` (_integer (int)_, required) Number of units billed in the line item. Example: `1000`. * `unitOfMeasure` (_string_, required) Unit of measure for the line item. Example: `kWh`. * `amount` (_number (double)_, required) Monetary amount of the line item. Example: `100`. * `currencyCode` (_string_, required) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create bill adjustment request `POST /accounts/{externalAccountId}/bills/adjustment` Creates a request to make a financial adjustment on an existing account or bill following a complaint or an investigation. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `0015f00000FpRVuAAK`. #### Request body Media type: `application/json`. Schema: `billAdjustmentRequest`. #### Responses * **201** Media type: `application/json`. Schema: `object`. Retrieves the generated bill for financial adjustment. * `externalBillId` (_string_, required) The billing system’s unique identifier of a single bill. Example: `0015f00000XpRVuCDE`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Retrieve billing consumption `GET /accounts/{externalAccountId}/bills/consumption` Retrieves the list of billing consumptions for the customer's account. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `001RN000002rEkrYAE`. * `startDate` (query, date-only) Optional. If provided, it defines the earliest bill date. Example: `2022-02-06`. * `endDate` (query, date-only) Optional. If provided, it defines the latest bill date. If blank, use current date. Example: `2022-02-06`. * `numberOfBills` (query, integer (int)) The number of bills to retrieve. If supplied, it overrides startDate to retrieve specified number of bills. Example: `1`. * `idType` (query, string) The ID type parameter of the billing system. The ID type can be an external account ID or an external customer reference ID. Example: `External Customer`. * `sortBy` (query, string) The field to use for sorting. Example: `billDate`. * `sortOrder` (query, string) The order of sorting. Example: `ASC, DESC`. * `offset` (query, integer (int)) The starting row offset into the result set returned by the query. Example: `5`. * `limit` (query, integer (int)) The number of bills to retrieve. Example: `5`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves a collection of the billed consumptions. * `billedConsumption` (_array of object_, required) Each item: Billed consumption details. * `billId` (_string_, required) Unique reference to a single bill in the billing system. Example: `001B000001NL5Z9IAL`. * `externalBillingAccountId` (_string_) Unique account of the the billing system. Example: `001B000001NL5Z9IAL`. * `billDate` (_date-only_, required) Date on which the bill is generated. Example: `2022-01-25`. * `totalBilledConsumption` (_number (double)_, required) Total billed consumption in a bill. Example: `1560.76`. * `meters` (_array of object_, required) Collection of meters linked to a bill. * `meterId` (_string_, required) Unique meter identifier with a collection of registers. Example: `M123`. * `externalServicePointId` (_string_) Unique servicePoint ID for the meter. Example: `M123`. * `serviceType` (_string_) Type of service this consumption belongs to. Example: `Gas`. * `registers` (_array of object_, required) * `registerId` (_string_, required) Unique register identifier within a meter. Example: `R124`. * `registerConsumption` (_number (double)_, required) Consumption related to the register. Example: `1000.67`. * `unitOfMeasure` (_string_, required) Unit of measure of the register. Example: `kWh`. * `timeOfUse` (_string_, required) Time period of use of the register. Example: `PEAK`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Generate a bill for an account `POST /accounts/{externalAccountId}/bills/generation` Creates a request to the billing system to generate a bill. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `001RN000002rEkrYAE`. #### Request body Media type: `application/json`. Schema: `billRequest`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves the generated bill. * `status` (_string_, required) The status of the bill generation request, such as success, error, or queued. Example: `Queued`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create contracts `POST /accounts/{externalAccountId}/contracts` Creates assets or contracts in the billing system based on the interaction with the customer using Salesforce. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `102883Y23YU`. #### Request body Media type: `application/json`. Schema: `contract`. #### Responses * **201** Media type: `application/json`. Schema: `object`. The contract was created. * `externalContractIds` (_array of string_, required) Items: Example: `0015f000004jXxjAAEe`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create account hold request `POST /accounts/{externalAccountId}/hold` Creates a request to place an account on billing hold due to a complaint or an investigation. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `0015f00000FpRVuAAK`. #### Request body Media type: `application/json`. Schema: `accountHoldRequest`. _Example_ ``` requestDateTime: 2022-01-28T07:07:35.808Z billId: 0015f00567FpRVilpK holdStartDate: 2022-01-29 requestReason: High Bill holdEndDate: 2022-01-30 ``` #### Responses * **204** The account is on billing hold. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Retrieve payments `GET /accounts/{externalAccountId}/payments` Retrieves a list of payments for the customer's account. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `0015f00000GoIVuAAN`. * `startDate` (query, date-only) Optional. If specified, the startDate property defines the earliest payment date. Specify either the startDate or numberOfPayments property but not both. Example: `2022-01-24`. * `endDate` (query, date-only) Optional. If specified, the endDate property defines the latest payment date. If the endDate property is blank, use the current date. Example: `2022-01-24`. * `numberOfPayments` (query, integer (int)) The number of payments to retrieve. Specify either the startDate or numberOfPayments property but not both. Example: `100`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves the collection of payments. * `payments` (_array of object_, required) Each item: Payment details. * `externalPaymentId` (_string_, required) Unique reference to a single payment in the billing system. Example: `10239474748590`. * `paymentDate` (_date-only_, required) Date when the payment was received. Example: `2022-01-24`. * `paymentAmount` (_number (double)_, required) Total paid amount. Example: `100`. * `currencyCode` (_string_, required) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `paymentMethod` (_string_, required) Method of payment, such as cash, direct debit, or check. Example: `Cash`. * `paymentStatus` (_string_, required) Status of payment, such as Paid, Pending, and so on. Example: `Paid`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create a payment plan `POST /accounts/{externalAccountId}/payments` Creates a payment plan in the billing system, based on the interaction with the customer via Salesforce. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `0015f00000GoIVuAAN`. #### Request body Media type: `application/json`. Schema: `paymentPlan`. #### Responses * **201** Media type: `application/json`. Schema: `object`. A payment plan is created. * `externalPaymentPlanId` (_string_, required) The billing system's unique identifier for the payment plan. Example: `1RN000002`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Retrieve meter details `GET /accounts/{externalAccountId}/servicePoints/{externalServicePointId}/meters` Retrieves technical details of a meter for the specified account-service point combination. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `a24NBloph`. * `externalServicePointId` (path, string, required) The billing system's unique identifier for the customer's service point. Example: `h7Yuqw45`. * `externalContractId` (query, string) The external identifier of the contract in the billing system. Example: `123`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves the technical details of a meter. * `registers` (_array of object_, required) Each item: Details of a single register within a meter. * `externalRegisterId` (_string_, required) External identifier of a register in the billing system. Example: `a5Jp9007`. * `digitsLeft` (_integer (int)_, required) Number of digits to the left of the decimal point. Example: `2`. * `digitsRight` (_integer (int)_, required) Number of digits to the right of the decimal point. Example: `2`. * `registerUoM` (_string_, required) Unit of measure for the register. Example: `KWH`. * `previousReading` (_number (double)_, required) Last reading quantity. Example: `200.16`. * `previousReadDate` (_date-only_, required) Date of the recent reading. Example: `2024-02-27`. * `externalMeterId` (_string_, required) External identifier of a meter in the billing system. Example: `aX866Ipo990`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Submit meter reading `POST /accounts/{externalAccountId}/servicePoints/{externalServicePointId}/meters` The meter reading details. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `a24NBloph`. * `externalServicePointId` (path, string, required) The billing system's unique identifier for the customer's service point. Example: `h7Yuqw45`. #### Request body Media type: `application/json`. Schema: `object`. The meter reading details. * `externalMeterId` (_string_, required) External identifier of the meter in the billing system. Example: `23RJKL768`. * `externalContractId` (_string_) External identifier of the contract in the billing system. Example: `123`. * `triggerBilling` (_boolean_) Indicates whether to create a bill based on the reading (true) or not (false). Example: `false`. * `readings` (_array of object_, required) * `registerId` (_string_, required) Identifier of the external register. Example: `41wet5YT78`. * `readingValue` (_number (double)_, required) Value of the register reading. Example: `100.56`. * `readDate` (_date-only_) Meter reading date. The default value is the current date if the value isn't provided. Example: `2022-01-31`. * `saveImplausibleRead` (_boolean_) Indicates whether to override any validation errors (true) or not (false). Example: `true`. #### Responses * **200** Media type: `application/json`. Schema: `object`. The status of a meter reading. * `registers` (_array of object_, required) * `registerId` (_string_, required) External identifier of a register in the billing system. Example: `45TYU89dfT`. * `readStatus` (_boolean_, required) Status of a reading, such as accepted or rejected. Example: `true`. * `readStatusReason` (_string_) Reason code for rejecting a reading status. Example: `2456`. * `externalMeterId` (_string_, required) External identifier of a meter in the billing system. Example: `23RTY567GHj`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Get customer financial transactions `GET /accounts/{externalAccountId}/financialTransactions` Retrieves the customer’s financial transactions. #### Parameters * `externalAccountId` (path, string, required) The external account that the bill is tagged to. Example: `AC786567`. * `startDate` (query, date-only, required) The start date to retrieve the financial transactions. Example: `2022-01-10`. * `endDate` (query, date-only) The endDate property defines the latest payment date. If the endDate property is blank, use the current date. Example: `2023-04-15`. * `transactionType` (query, string) The type of transaction, such as a bill, statement, invoice, payment, or refund. Example: `Bill`. * `offset` (query, integer (int)) The number of transactions to be skipped before returning the first transaction. Example: `0`. * `limit` (query, integer (int)) The maximum number of records to return. Example: `10`. * `sortBy` (query, string) The fields that can be used to sort the records. Example: `transactionDate`. * `sortOrder` (query, string) The order for sorting the records. Example: `asc`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves the collection of the account’s financial transactions. * `financialTransactions` (_array of object_, required) The financial transaction details. Each item: Financial transaction details. * `transactionDate` (_date-only_, required) Date of the transaction. Example: `2024-01-15`. * `transactionType` (_string_) Type of transaction, such as a bill, statement, invoice, payment, or refund. Example: `Bill`. * `transactionDescription` (_string_) Description of the transaction. Example: `Bill for the Month of December`. * `transactionAmount` (_number (double)_, required) Transaction amount. A positive amount indicates a debit transaction, and a negative amount indicates a credit transaction. Example: `1000`. * `currencyCode` (_string_, required) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `accountBalance` (_number (double)_) Account balance after the transaction. Example: `2000`. * `transactionReference` (_string_) Transaction’s optional reference ID in the billing system. Example: `BI45786`. * `transactionDueDate` (_date-only_) Optional. Specifies the date when the transaction is due. Example: `2022-01-30`. * `transactionStatus` (_string_) Status of the transaction, such as pending or finalized. Example: `Paid`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create premises `POST /premises` Creates premises in the billing system, based on the customer interaction via Salesforce. #### Request body Media type: `application/json`. Schema: `object`. Details of the premises. * `premisesCountry` (_string_) Country of the premises. Example: `USA`. * `premisesId` (_string_, required) Unique identifier for the premises in Salesforce. Example: `A123455Lo9K`. * `geolocation` (_string_) Geographical location of the premises. Example: `{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }`. * `premisesPostalCode` (_string_) Postal code of the premises. Example: `10003`. * `premisesState` (_string_) State of the premises. Example: `New York`. * `requestDateTime` (_datetime (rfc3339)_, required) The timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-02-20T20:43:16.000Z`. * `premisesCity` (_string_) City of the premises. Example: `New York City`. * `externalAccountId` (_string_) The external account that the bill is tagged to. Example: `a3E5f000000xTx8LAF`. * `premisesName` (_string_, required) Name of the premises. Example: `5 Whitehill Rd, Newcraighall, Edinburgh, Scotland, EH15 3HR, United Kingdom`. * `premisesStreetAddress` (_string_) Street address of the premises. Example: `Main St`. * `premisesHouseNumber` (_string_) House number of the premises. Example: `34`. #### Responses * **201** Media type: `application/json`. Schema: `object`. * `externalPremisesId` (_string_, required) The billing system's unique identifier for the premises. Example: `P45612`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create a service point `POST /premises/{externalPremisesId}/servicePoints` Creates a service point in the billing system based on the interaction with the customer via Salesforce. #### Parameters * `externalPremisesId` (path, string, required) The billing system's unique identifier for the premises. Example: `a3E5f000000xTx8LAF`. #### Request body Media type: `application/json`. Schema: `object`. * `premisesId` (_string_) The unique identifier for the premises in Salesforce. Example: `A123455Lo9K`. * `requestDateTime` (_datetime (rfc3339)_, required) The timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-02-27T20:24:07.000Z`. * `servicePoints` (_array of object_, required) Each item: Details of a service point. * `servicePointId` (_string_, required) Unique identifier for the service point in Salesforce. Example: `S45678`. * `servicePointName` (_string_, required) Name of the service point. Example: `SL-ED847829`. * `serviceType` (_string_) Type of service, such as electricity, gas, or water. Example: `Electricity`. * `status` (_string_) Condition of the service point, such as active, disconnected, or abolished. Example: `Active`. * `marketIdentifier` (_string_) Unique reference within a specific market. Example: `M123`. #### Responses * **201** Media type: `application/json`. Schema: `object`. Retrieves a collection of the billing system's unique identifiers for the service points. * `externalServicePointIds` (_array of string_, required) Items: Example: `0015f000004jXxjAAE`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create a customer `POST /customers` Creates a customer in the billing system, based on the customer interaction via Salesforce. #### Request body Media type: `application/json`. Schema: `object`. Customer details. * `mailingStreetAddress` (_string_) Mailing street address of the customer. Example: `Main St`. * `mailingCity` (_string_) Mailing city of the customer. Example: `San Jose`. * `lastName` (_string_, required) Last name of the customer. Example: `Rogers`. * `mailingState` (_string_) Mailing state of the customer. Example: `California`. * `company` (_string_) Company of the customer. Example: `Green Energy`. * `title` (_string_) Customer salutation. Example: `Mr.`. * `firstName` (_string_) First name of the customer. Example: `Josh`. * `mailingPostalCode` (_string_) Mailing postal code of the customer. Example: `94088`. * `email` (_string_, required) Email address of the customer. Example: `abc@example.com`. * `requestDateTime` (_datetime (rfc3339)_, required) The timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-01-25T06:22:17.772Z`. * `phoneAreaCode` (_string_) Area code of the customer's phone number. Example: `011`. * `fax` (_string_) Fax number of the customer. Example: `(123)-456-7890`. * `phone` (_string_) Phone number of the customer. Example: `28526134`. * `mobilePhone` (_string_) Mobile phone number of the customer. Example: `9812347650`. * `mobilePhoneAreaCode` (_string_) Area code of the customer's mobile phone number. Example: `91`. * `contactId` (_string_, required) The unique identifier for the contact in Salesforce. Example: `83892`. * `mailingHouseNumber` (_string_) Mailing house number of the customer. Example: `152`. * `status` (_string_) Status of the customer. Example: `Active or Inactive`. * `mailingCountry` (_string_) Mailing country of the customer. Example: `USA`. #### Responses * **201** Media type: `application/json`. Schema: `object`. * `externalCustomerId` (_string_, required) The billing system's unique identifier for the customer. Example: `001RN000002rEkrYAE`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### PUT Update customer details `PUT /customers/{externalCustomerId}` Updates a customer's details in the billing system, based on the customer interaction via Salesforce. #### Parameters * `externalCustomerId` (path, string, required) The billing system's unique identifier for the customer. Example: `001RN000002rEkrYAE`. #### Request body Media type: `application/json`. Schema: `object`. Customer details. * `mailingStreetAddress` (_string_) Mailing street address of the customer. Example: `Main St`. * `mailingCity` (_string_) Mailing city of the customer. Example: `San Jose`. * `lastName` (_string_, required) Last name of the customer. Example: `Rogers`. * `mailingState` (_string_) Mailing state of the customer. Example: `California`. * `company` (_string_) Company of the customer. Example: `Green Energy`. * `title` (_string_) Customer salutation. Example: `Mr.`. * `firstName` (_string_) First name of the customer. Example: `Josh`. * `mailingPostalCode` (_string_) Mailing postal code of the customer. Example: `94088`. * `email` (_string_, required) Email address of the customer. Example: `abc@example.com`. * `requestDateTime` (_datetime (rfc3339)_, required) The timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-01-25T06:22:17.772Z`. * `phoneAreaCode` (_string_) Area code of the customer's phone number. Example: `011`. * `fax` (_string_) Fax number of the customer. Example: `(123)-456-7890`. * `phone` (_string_) Phone number of the customer. Example: `28526134`. * `mobilePhone` (_string_) Mobile phone number of the customer. Example: `9812347650`. * `mobilePhoneAreaCode` (_string_) Area code of the customer's mobile phone number. Example: `91`. * `contactId` (_string_, required) The unique identifier for the contact in Salesforce. Example: `83892`. * `mailingHouseNumber` (_string_) Mailing house number of the customer. Example: `152`. * `status` (_string_) Status of the customer. Example: `Active or Inactive`. * `mailingCountry` (_string_) Mailing country of the customer. Example: `USA`. #### Responses * **200** Media type: `application/json`. Schema: `object`. * `externalCustomerId` (_string_, required) The billing system's unique identifier for the customer. Example: `001RN000002rEkrYAE`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create customer contracts `POST /contracts` Creates customer contracts in the billing system based on the interaction with the customer. #### Request body Media type: `application/json`. Schema: `createCustomerContract`. #### Responses * **201** Media type: `application/json`. Schema: `object`. The customer contract was created. * `salesforceId` (_string_, required) ID of the contract as stored in Salesforce. Example: `a3E5f000000xT627nay`. * `statusChangeDate` (_date-only_) Date when the status was changed. Example: `2022-02-28`. * `endDate` (_date-only_) End date of service. Example: `2024-02-28`. * `billingSchedule` (_string_) Billing schedule of the customer contract. Example: `weekly`. * `id` (_string_) ID of the contract item. Example: `a3E5f000000xT627nay`. * `activationDate` (_date-only_, required) Activation date of the energy service agreement. Example: `2022-02-28`. * `accountId` (_string_, required) Unique billing account ID. Example: `wjoEKDM983`. * `startDate` (_date-only_, required) Start date of service. Example: `2024-02-28`. * `product` (_object_, required) Product in the billing system. * `id` (_string_) Specifies the external identifier of a product in the billing system. Example: `a3E5f000000xTx8LAF`. * `salesforceId` (_string_) The identifier of a product in the billing system. Example: `a3E5f000000xT627`. * `physicalProductId` (_string_) A reference to the product of physical goods. Example: `a3E5f000000xT627`. * `customerId` (_string_, required) Unique identifier of the customer. Example: `a3E5f000000xTx8LAF`. * `statusReason` (_string_) Reason for the current customer contract status. Example: `Inactive because of dues`. * `contractItems` (_array of object_) Each item: Creates customer contract items in the billing system based on the interaction with the customer. * `id` (_string_) ID of the contract item. Example: `a3E5f000000xT627nay`. * `salesforceId` (_string_, required) ID of the contract as stored in Salesforce. Example: `a3E5f000000xT627nay`. * `account` (_string_) Unique billing account ID. Example: `a3E5f000000xTx8LAF`. * `contractId` (_string_) ID of the contract in the billing system. Example: `wjoEKDM983`. * `product` (_object_) Product in the billing system. * `id` (_string_) Specifies the external identifier of a product in the billing system. Example: `a3E5f000000xTx8LAF`. * `salesforceId` (_string_) The identifier of a product in the billing system. Example: `a3E5f000000xT627`. * `physicalProductId` (_string_) A reference to the product of physical goods. Example: `a3E5f000000xT627`. * `locationId` (_string_) ID of the location. Example: `E-BS93214`. * `servicePointId` (_string_) Unique identifier of the service point in Salesforce. Example: `E-ED9871617`. * `startDate` (_date-only_) Start date of service. Example: `2022-02-28`. * `endDate` (_date-only_) End date of service. Example: `2022-02-28`. * `oneTimeCharge` (_string_) One-time charge of the asset. Example: `17`. * `recurringCharge` (_string_) Cyclic charges of the asset. Example: `189`. * `recurringPricePeriod` (_string_) Period during which the recurring price is scheduled for the product. Example: `189`. * `usagePeriod` (_string_) Usage period of the service point. Example: `189`. * `usageQuantity` (_string_) Usage quantity of the service point. Example: `189`. * `usageCharge` (_string_) Usage-based price of the asset. Example: `189`. * `usageUnitofMeasure` (_string_) Unit of measure for the usage. Example: `189`. * `type` (_string_, required) Service type. Example: `Gas`. * `status` (_string_) Service status. Example: `Active`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### PUT Update customer contracts `PUT /contracts/{contractId}` Update contracts in the billing system based on the interaction with the customer. #### Parameters * `contractId` (path, string, required) #### Request body Media type: `application/json`. Schema: `updateCustomerContract`. #### Responses * **201** Media type: `application/json`. Schema: `object`. The contract was updated. * `externalContractId` (_string_, required) The unique identifier for the contract in the billing system. Example: `0015f000004jXxjAAEe`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### PATCH Patch contract `PATCH /contracts/{contractId}` Updates contracts in the billing system based on the interaction with the customer. #### Parameters * `contractId` (path, string, required) #### Request body Media type: `application/json`. Schema: `patchCustomerContract`. #### Responses * **204** Media type: `application/json`. Schema: `any`. No Content Type: `any`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create customer contract items `POST /contracts/{contractId}/items` Creates contract items in the billing system based on the interaction with the customer. #### Parameters * `contractId` (path, string, required) #### Request body Media type: `application/json`. Schema: `createCustomerContractItem`. #### Responses * **201** Media type: `application/json`. Schema: `object`. The contract items were created. * `salesforceId` (_string_, required) ID of the contract as stored in Salesforce. Example: `a3E5f000000xT627nay`. * `endDate` (_date-only_) End date of service. Example: `2022-02-28`. * `usagePeriod` (_string_) Usage period of the service point. Example: `189`. * `recurringPricePeriod` (_string_) Period during which the recurring price is scheduled for the product. Example: `189`. * `id` (_string_) ID of the contract item. Example: `a3E5f000000xT627nay`. * `account` (_string_) Unique billing account ID. Example: `a3E5f000000xTx8LAF`. * `recurringCharge` (_string_) Cyclic charges of the asset. Example: `189`. * `startDate` (_date-only_) Start date of service. Example: `2022-02-28`. * `usageCharge` (_string_) Usage-based price of the asset. Example: `189`. * `product` (_object_) Product in the billing system. * `id` (_string_) Specifies the external identifier of a product in the billing system. Example: `a3E5f000000xTx8LAF`. * `salesforceId` (_string_) The identifier of a product in the billing system. Example: `a3E5f000000xT627`. * `physicalProductId` (_string_) A reference to the product of physical goods. Example: `a3E5f000000xT627`. * `contractId` (_string_) ID of the contract in the billing system. Example: `wjoEKDM983`. * `usageUnitofMeasure` (_string_) Unit of measure for the usage. Example: `189`. * `usageQuantity` (_string_) Usage quantity of the service point. Example: `189`. * `oneTimeCharge` (_string_) One-time charge of the asset. Example: `17`. * `servicePointId` (_string_) Unique identifier of the service point in Salesforce. Example: `E-ED9871617`. * `locationId` (_string_) ID of the location. Example: `E-BS93214`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### PUT Update customer contract items `PUT /contracts/{contractId}/items/{itemsId}` Updates contracts items in the billing system based on the interaction with the customer. #### Parameters * `contractId` (path, string, required) * `itemsId` (path, string, required) #### Request body Media type: `application/json`. Schema: `updateCustomerContractItem`. #### Responses * **201** Media type: `application/json`. Schema: `object`. The contract items were updated. * `externalContractItemId` (_string_, required) The unique identifier for the contract item in the billing system. Example: `0015f000004jXxjAAEe`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Create customer infrastructure request `POST /generic/customersInfrastructure` Creates a customer and the related contracts in the billing system. #### Request body Media type: `application/json`. Schema: `object`. The details of a customer infrastructure request. * `customer` (_object_, required) Customer details. * `accountType` (_string_) Type of the account, such as consumer or business. Example: `Green Energy`. * `mailingStreetAddress` (_string_) Mailing street address of the customer. Example: `Main St`. * `mailingCity` (_string_) Mailing city of the customer. Example: `San Jose`. * `lastName` (_string_, required) Last name of the customer. Example: `Rogers`. * `mailingState` (_string_) Mailing state of the customer. Example: `California`. * `company` (_string_) Company of the customer. Example: `Green Energy`. * `title` (_string_) Customer salutation. Example: `Mr.`. * `firstName` (_string_) First name of the customer. Example: `Josh`. * `mailingPostalCode` (_string_) Mailing postal code of the customer. Example: `94088`. * `accountId` (_string_, required) Unique identifier for the account in Salesforce. Example: `83892`. * `email` (_string_, required) Email address of the customer. Example: `abc@example.com`. * `phoneAreaCode` (_string_) Area code of the customer's phone number. Example: `011`. * `fax` (_string_) Fax number of the customer. Example: `(123)-456-7890`. * `phone` (_string_) Phone number of the customer. Example: `28526134`. * `mobilePhone` (_string_) Mobile phone number of the customer. Example: `9812347650`. * `contacts` (_array of object_, required) Contact details of the customer. Each item: Contact details. * `title` (_string_) Salutation of the user. Example: `Mr.`. * `company` (_string_) Company name of the user. Example: `Green Energy`. * `firstName` (_string_) First name of the user. Example: `Josh`. * `lastName` (_string_, required) Last name of the user. Example: `Roger`. * `email` (_string_, required) Email address of the user. Example: `abc@example.com`. * `phone` (_string_) Phone number of the user. Example: `5552613334`. * `phoneAreaCode` (_string_) Phone area code of the user's phone number. Example: `011`. * `mobilePhone` (_string_) Mobile phone number of the user. Example: `9812347650`. * `mobilePhoneAreaCode` (_string_) Area code of the user's mobile phone number. Example: `91`. * `mailingHouseNumber` (_string_) House number of the user's mailing address. Example: `152`. * `mailingStreetAddress` (_string_) Street of the user's mailing address. Example: `Main St`. * `mailingCity` (_string_) City of the user's mailing address. Example: `San Jose`. * `mailingState` (_string_) State of the user's mailing address. Example: `California`. * `mailingPostalCode` (_string_) Postal code of the mailing address. Example: `94088`. * `mailingCountry` (_string_) Country of the user's mailing address. Example: `USA`. * `contactId` (_string_, required) Unique identifier for the contact in Salesforce. Example: `83892`. * `contactType` (_string_, required) Contact type in Salesforce. Example: `Business`. * `mobilePhoneAreaCode` (_string_) Area code of the customer's mobile phone number. Example: `91`. * `mailingHouseNumber` (_string_) Mailing house number of the customer. Example: `152`. * `status` (_string_) Status of the customer. Example: `Active or Inactive`. * `mailingCountry` (_string_) Mailing country of the customer. Example: `USA`. * `premises` (_object_, required) Details of the premises. * `premisesName` (_string_, required) Name of the premises. Example: `5 Whitehill Rd, Newcraighall, Edinburgh, Scotland, EH15 3HR, United Kingdom`. * `premisesHouseNumber` (_string_) House number of the premises. Example: `34`. * `premisesStreetAddress` (_string_) Street address of the premises. Example: `Main St`. * `premisesCity` (_string_) City of the premises. Example: `New York City`. * `premisesState` (_string_) State of the premises. Example: `New York`. * `premisesCountry` (_string_) Country of the premises. Example: `USA`. * `premisesPostalCode` (_string_) Postal code of the premises. Example: `10003`. * `geolocation` (_string_) Geographical location of the premises. Example: `{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }`. * `premisesId` (_string_, required) Unique identifier for the premises in Salesforce. Example: `A123455Lo9K`. * `servicePoints` (_array of object_, required) Details of a service point. * `servicePointId` (_string_, required) Unique identifier for the service point in Salesforce. Example: `S45678`. * `servicePointName` (_string_, required) Name of the service point. Example: `SL-ED847829`. * `serviceType` (_string_) Type of service, such as electricity, gas, or water. Example: `Electricity`. * `status` (_string_) Condition of the service point, such as active, disconnected, or abolished. Example: `Active`. * `marketIdentifier` (_string_) Unique reference within a specific market. Example: `M123`. * `requestDateTime` (_datetime (rfc3339)_, required) The timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-01-25T06:22:17.772Z`. * `contract` (_object_) Contract details. * `contractId` (_string_) Unique identifier for the contract in Salesforce. Example: `12A`. * `status` (_string_) Status of the contract, for example, active or inactive. Example: `Active`. * `type` (_string_) Type of the contract. Example: `Energy`. * `assets` (_array of object_, required) Asset's details. Each item: Request to create the contracts. * `productCode` (_string_) Unique product identifier. Example: `IP234`. * `parentAsset` (_string_) Name of the parent asset. If the parentAsset property isn’t specified, then the parent asset is the highest level product that was sold. Example: `Head Office Electricity`. * `productDescription` (_string_) Product name or the cost component name if the parent asset is also available. Example: `connection of broadband`. * `serviceEndDate` (_date-only_) End date of the service. Example: `2024-01-24`. * `recurringCharge` (_number (double)_) Cyclic charges of the asset. Example: `30`. * `currencyCode` (_string_) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `usageCharge` (_number (double)_) Usage-based price of the asset. Example: `17`. * `serviceStartDate` (_date-only_) Start date of the service. Example: `2024-01-24`. * `servicePoint` (_string_) Name of the service point. Example: `E-BS93214`. * `oneTimeCharge` (_number (double)_) One-time charge of the asset. Example: `190`. * `assetId` (_string_, required) Unique identifier for the asset in Salesforce. Example: `a3E5f000000xTx8LAF`. * `assetName` (_string_, required) Name of the asset. Example: `Southern Region Electricity`. * `status` (_string_) Status of the asset. Example: `Active`. * `billingAccount` (_object_, required) Details of the billing account. * `accountName` (_string_, required) Name of the account. Example: `Northern Region`. * `accountId` (_string_, required) Unique identifier for the account in Salesforce. Example: `0015f000004jXxjZZZ`. * `status` (_string_) Status of the account. Example: `Active`. * `fax` (_string_) Fax number of the account. Example: `555-123-4567`. * `phone` (_string_) Phone number of the account. Example: `5551234567`. * `phoneAreaCode` (_string_) Area code of the account's phone number. Example: `+1`. * `mobilePhone` (_string_) Specifies the mobile phone number of the account. Example: `5551234567`. * `mobilePhoneAreaCode` (_string_) Mobile phone area code of the account. Example: `+1`. * `billingHouseNumber` (_string_) House number of the billing address. Example: `B-507`. * `billingStreetAddress` (_string_) Street of the billing address. Example: `Main St`. * `billingCity` (_string_) City of the billing address. Example: `New York`. * `billingState` (_string_) State of the billing address. Example: `New York`. * `billingPostalCode` (_integer (int)_) Postal code of the billing address. Example: `10003`. * `billingCountry` (_string_) Country of the billing address. Example: `USA`. * `billingFrequency` (_string_) Frequency of billing, such as monthly or quarterly. Example: `Monthly`. * `billDeliveryMethod` (_string_) Bill delivery method, such as paper, electronic, or email. Example: `Paper`. #### Responses * **201** Media type: `application/json`. Schema: `object`. The details of the customer infrastructure response. * `externalContractIds` (_array of string_, required) The external identifiers for contracts in the billing system. Items: Example: `0015f000004jXxjAAEe`. * `externalCustomerId` (_string_) The billing system's unique identifier for the customer. Example: `ab12304`. * `externalPremises` (_array of object_) The billing system's unique identifier for the premises. * `premiseId` (_string_, required) Example: `A123455Lo9K`. * `externalPremiseId` (_string_, required) Example: `A123455Lo8G`. * `externalServicePoints` (_array of object_) The billing system's unique identifier for the service point. * `servicePointId` (_string_, required) Example: `S45678`. * `externalServicePointId` (_string_, required) Example: `S45699`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Get customer meter readings `GET /meters` Retrieves the technical details of a meter and the meter readings. #### Parameters * `externalId` (query, string) The unique reference ID of the billing system. Example: `AC567878`. * `externalServicePointId` (query, string) The billing system's unique identifier for the customer's service point. Example: `AC567878`. * `externalPremiseId` (query, string) The external identifier of the premises in the billing system. Example: `AC567878`. * `serviceType` (query, string) The serviceType of the billing system. Example: `AC567878`. * `startDate` (query, date-only) The start date for which to fetch the meter reading. Example: `2023-05-01`. * `endDate` (query, date-only) The end date for which to fetch the meter reading. Example: `2023-10-01`. * `offset` (query, integer (int)) The starting row offset into the result set returned by the query. Example: `1000`. * `limit` (query, integer (int)) Allows you to limit the number of rows returned by query. Example: `1000`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves the technical details of a meter. * `meters` (_array of object_, required) Collection of meters. * `externalMeterId` (_string_, required) External identifier of a meter in the billing system. Example: `KEH1478987`. * `deviceType` (_string_) Type of meter. Example: `Postpay`. * `externalId` (_string_) Billing system's unique identifier. Example: `Acme`. * `externalPremiseId` (_string_) External identifier of the premises in the billing system. Example: `Premise_0002`. * `serviceType` (_string_) Type of Service. Example: `Electricity`. * `externalServicePointId` (_string_) Billing system's unique identifier for the customer's service point. Example: `E-ED9871617`. * `manufactureName` (_string_) Name of the device manufacturer. Example: `Siemens`. * `manufactureSerialNumber` (_string_) Serial number of the device manufacturer. Example: `SIE14052003`. * `registers` (_array of object_, required) Collection of details for each register on a meter. * `externalRegisterId` (_string_, required) External identifier of a register in the billing system. Example: `01`. * `digitsLeft` (_integer (int)_) Number of digits to the left of the decimal point. Example: `5`. * `digitsRight` (_integer (int)_) Number of digits to the right of the decimal point. Example: `2`. * `registerUoM` (_string_) Unit of measure for the register. Example: `kWh`. * `numberOfDials` (_string_) Total number of dials in the register. Example: `1`. * `readings` (_array of object_, required) Collection of meter readings. * `previousReading` (_number (double)_) Previous reading quantity. Example: `5456`. * `previousReadDate` (_date-only_) Date of the previous reading. Example: `2024-01-10`. * `currentMeterReading` (_number (double)_) Current reading quantity. Example: `6456`. * `currentReadDate` (_date-only_) Date of the recent reading. Example: `2024-04-14`. * `consumption` (_number (double)_) Consumption quantity. Example: `1000`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Get customer payments `GET /payments` Retrieves a list of payments. #### Parameters * `externalId` (query, string, required) The unique reference ID of the billing system. Example: `AC5467898`. * `idType` (query, string, required) The ID type parameter of the billing system. The ID type can be an external account ID or an external customer reference ID. Example: `External Customer`. * `startDate` (query, date-only) Optional. If specified, the startDate property defines the earliest payment date. Specify either the startDate or numberOfPayments property but not both. Example: `2023-01-15`. * `endDate` (query, date-only) Optional. If specified, the endDate property defines the latest payment date. If the endDate property is blank, use the current date. Example: `2023-04-15`. * `numberOfPayments` (query, integer (int)) The number of payments to retrieve. Specify either the startDate or numberOfPayments property but not both. Example: `10`. * `sortBy` (query, string) The field to use for sorting. Example: `paymentDate`. * `sortOrder` (query, string) The order of sorting. Example: `ASC, DESC`. * `offset` (query, integer (int)) Optional. The starting row offset into the result set returned by the query. Example: `5`. * `limit` (query, integer (int)) Optional. The number of payments to retrieve. Example: `5`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves the collection of payments. * `payments` (_array of object_, required) Each item: Payment details. * `paymentStatus` (_string_, required) Status of payment, such as Paid, Pending, and so on. Example: `Paid`. * `paymentDate` (_date-only_, required) Date when the payment was received. Example: `2022-01-24`. * `paymentMethod` (_string_, required) Method of payment, such as cash, direct debit, or check. Example: `Cash`. * `currencyCode` (_string_, required) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `paymentAmount` (_number (double)_, required) Total paid amount. Example: `100`. * `externalPaymentId` (_string_, required) Unique reference to a single payment in the billing system. Example: `10239474748590`. * `externalAccountId` (_string_, required) The external account that the bill is tagged to. Example: `AC376869`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Get customer payment line items `GET /payments/{externalPaymentId}` Retrieves a list of payment line items of a specific payment. #### Parameters * `externalPaymentId` (path, string, required) The unique reference to a single payment in the billing system. Example: `AC36879`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves collection of Payment Line Items. * `externalPaymentId` (_string_, required) The unique reference to a single payment in the billing system. Example: `PY347879`. * `paymentDate` (_date-only_, required) The date when the payment was received. Example: `2023-03-23`. * `paymentLineItems` (_array of object_, required) The payment line items. Each item: Payment line item. * `externalPaymentLineItemId` (_string_, required) Line item ID of the payment list. Example: `01`. * `clearedAmount` (_number (double)_, required) Total cleared amount against the line item. Example: `350`. * `clearedDate` (_date-only_, required) Date when the payment was received. Example: `2023-03-26`. * `clearingReason` (_string_, required) Reason for clearing the payment. Example: `Bill payment`. * `clearingReference` (_string_, required) Clearance reference of the line item. Example: `CA567898`. * `dateDeferral` (_date-only_, required) Date to defer the payment to. Example: `2023-04-25`. * `taxAmount` (_number (double)_, required) Tax amount for the line item. Example: `175`. * `dueDate` (_date-only_, required) Date when the payment is due. Example: `2023-03-24`. * `amountDue` (_number (double)_) Amount due for payment. Example: `100`. * `externalBillId` (_string_) Unique identifier of the bill payment. Example: `CA567898`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Retrieve customer’s account balance `GET /balances` Retrieves the current balance, latest bill, and payment amounts from the given date. #### Parameters * `externalId` (query, string, required) The unique reference ID of the billing system. Example: `AC5467898`. * `idType` (query, string, required) The ID type parameter of the billing system. The ID type can be an external account ID or an external customer reference ID. Example: `External Customer`. * `balanceDate` (query, date-only) The date when the balance is requested. If the balanceDate property isn’t specified, the current date is the default value. Example: `2023-04-20`. #### Responses * **200** Media type: `application/json`. Schema: `object`. The account balance details. * `minimumAmount` (_number (double)_) Minimum payment amount required to avoid collection action. Example: `11.8`. * `nextPaymentAmount` (_number (double)_) Amount applicable if billed but not paid. If a zero account balance is found or the amount is paid, then no response is provided. Example: `100.5`. * `overdueAmount` (_number (double)_) Unpaid previous balance amount. Example: `100.7`. * `nextPaymentDueDate` (_date-only_) Due date for the next payment. If the due date for the next payment isn’t applicable, then no response is provided. Example: `2022-01-25`. * `overdueDate` (_date-only_) Specifies when the payment is overdue based on the payment due date. Example: `2023-04-20`. * `currencyCode` (_string_) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `minimumPaymentDate` (_date-only_) Due date for the minimum payment to avoid collection action. Example: `2024-01-25`. * `currentBalance` (_number (double)_, required) Amount that’s owed, which includes the current balance and overdue balance. Example: `240.6`. * `lastPaymentAmount` (_number (double)_) Last paid bill amount. Example: `130.9`. * `lastBillAmount` (_number (double)_) Last bill amount. Example: `230.1`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### POST Fetch service points. `POST /servicepoints` Fetches service points for a given address. #### Request body Media type: `application/json`. Schema: `servicePointsRequest`. #### Responses * **200** Media type: `application/json`. Schema: `object`. The service points retrieved for this address. * `distributionRegion` (_string_, required) Distribution region. Example: `San Jose`. * `distributorCode` (_string_, required) Distributor code. Example: `D11`. * `tradingStatus` (_string_, required) Status of the trading. Example: `Live`. * `address` (_object_, required) Address. * `street` (_string_, required) Street of the address. Example: `34 Main St`. * `state` (_string_, required) State of the address. Example: `CA`. * `postalCode` (_string_, required) Postal Code of the address. Example: `95110`. * `city` (_string_, required) City of the address. Example: `San Jose`. * `country` (_string_, required) Country of the address. Example: `USA`. * `marketIdentifier` (_string_, required) Market identifier. Example: `M00001`. * `serviceType` (_string_, required) Service type. Example: `Gas`. * `servicePointId` (_string_, required) ID of the service point. Example: `SP-0001`. * `status` (_string_, required) Service point status. Values are Active or Inactive. Example: `Active`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Get customer bills `GET /bills` Retrieves a list of bills. #### Parameters * `externalId` (query, string, required) The unique reference ID of the billing system. Example: `AC5467898`. * `idType` (query, string, required) The ID type parameter of the billing system. The ID type can be an external account ID or an external customer reference ID. Example: `External Customer`. * `startDate` (query, date-only) Optional. If specified, defines the billing start date. Example: `2023-01-10`. * `endDate` (query, date-only) Optional. If specified, defines the billing end date. If not specified, the current date is used. Example: `2023-04-10`. * `numberOfBills` (query, integer (int)) Optional. The number of bills to retrieve. If specified, override the startDate property, if necessary to retrieve the specified number of bills. Example: `5`. * `paymentStatus` (query, string) The payment status for this account. Example: `paid or due`. * `serviceType` (query, string) The type of service for the bill. Example: `Gas, Electricity`. * `sortBy` (query, string) The field to use for sorting. Example: `billDate`. * `sortOrder` (query, string) The order of sorting. Example: `ASC , DESC`. * `offset` (query, integer (int)) Optional. The starting row offset into the result set returned by the query. Example: `5`. * `limit` (query, integer (int)) Optional. The number of bills to retrieve. Example: `5`. * `externalPremiseId` (query, string) The unique ID of the premises in the external billing system. Example: `EP-KJDNOR23`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves a collection of bills. * `bills` (_array of object_, required) * `externalBillId` (_string_, required) The billing system’s unique identifier of a single bill. Example: `2378`. * `billDate` (_date-only_, required) The date when the bill is generated, which is the end date of the billing period. Example: `2023-01-25`. * `billAmount` (_number (double)_, required) The total bill amount including taxes. Example: `1345`. * `billDueDate` (_date-only_, required) The due date to pay the bill. Example: `2023-01-25`. * `billUrl` (_string_) The link to the copy of the bill. Example: `www.test.com/decbill`. * `currencyCode` (_string_, required) The currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `taxAmount` (_number (double)_, required) The tax amount for the bill. Example: `346`. * `billStartDate` (_date-only_, required) The bill start date. Example: `2023-01-12`. * `billEndDate` (_date-only_, required) The bill end date. Example: `2023-01-14`. * `billType` (_string_) The bill types, such as bills, invoices, summaries, and PAYG statements. Example: `Invoice`. * `billStatus` (_string_, required) The bill’s status, such as canceled, completed, or in-progress. Example: `Created`. * `externalAccountId` (_string_, required) The external account that the bill is tagged to. Example: `AC7865756`. * `lastPaymentDate` (_date-only_) The date of last payment made against the account. Example: `2023-01-14`. * `lastPaymentAmount` (_number (double)_) The amount of last payment made against the account. Example: `346`. * `additionalDiscount` (_number (double)_) An additional discount provided for the account. Example: `35`. * `averageTemperature` (_string_) The average temperature of the demographic for the billing period. Example: `37c`. * `billPeriodDays` (_integer (int)_) The billing period days from start date to end date. Example: `346`. * `currentBalance` (_number (double)_) The current balance of the account. Example: `346`. * `currentCharges` (_number (double)_) The charges applied for the current billing period. Example: `346`. * `overdueAmount` (_number (double)_) The overdue amount for the account. Example: `346`. * `paymentStatus` (_string_) The payment status for this account. * `lastBillAmount` (_number (double)_) The last bill amount for the account. Example: `346`. * `lastBillDate` (_date-only_) The last bill date for the account. Example: `2023-01-14`. * `externalBillingAccountId` (_string_) The external account that the bill is tagged to. Example: `AC7865756`. * `servicePoint` (_array of object_) * `externalPremiseId` (_string_) The unique ID of the premises in the external billing system. Example: `EP-KJDNOR23`. * `externalServicePointId` (_string_) The service point ID for the service provided. Example: `AC7865756jsybeo`. * `serviceType` (_string_) The service type at the premises. Example: `Gas`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ### GET Get customer bill line items `GET /bills/{externalBillId}` Retrieves a list of the bill line items for the specified bill ID. #### Parameters * `externalBillId` (path, string, required) The billing system’s unique identifier of a single bill. Example: `2378`. #### Responses * **200** Media type: `application/json`. Schema: `object`. Retrieves a collection of the bill line items. * `billLineItems` (_array of object_, required) The collection of bill line items. * `externalBillLineItemId` (_string_, required) The unique reference to a line item within a bill in the billing system. Example: `01`. * `lineItemDescription` (_string_, required) The text displayed for the line item. Example: `Consumption`. * `usageQty` (_integer (int)_, required) The number of units billed in the line item. Example: `1000`. * `unitOfMeasure` (_string_, required) The unit of measure for the line item. Example: `kWh`. * `amount` (_number (double)_, required) The monetary amount of the line item, including taxes. This property is used when the taxes aren’t separate line items. Example: `1500`. * `currencyCode` (_string_, required) The currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `taxAmount` (_number (double)_) The monetary amount of the tax. This property is used when the tax isn't a separate line item. Example: `350`. * **400** There was an issue with your request. Media type: `application/json`. Schema: `errorMessage`. * **401** Authorization failed. Media type: `application/json`. Schema: `errorMessage`. * **403** Request forbidden. Media type: `application/json`. Schema: `errorMessage`. * **404** Resource not found. Media type: `application/json`. Schema: `errorMessage`. * **405** Method not allowed. Media type: `application/json`. Schema: `errorMessage`. * **415** Unsupported media type. Media type: `application/json`. Schema: `errorMessage`. * **422** Unprocessable entity. Media type: `application/json`. Schema: `errorMessage`. * **500** Unable to complete the request as the server encountered an error. Media type: `application/json`. Schema: `errorMessage`. ## Schemas ### errorMessage Shown when an API throws an error, typically with an HTTP error response code (3xx, 4xx, or 5xx). * `errorCode` (_string_) Application-relevant detail defined in the API or a common list. * `statusCode` (_string_) HTTP error code extension. * `reason` (_string_) Reason for the error, which can be shown to a client user. * `message` (_string_) Provides more details and corrective actions related to the error, which can be shown to a client user. * `referenceError` (_string_) The URI of the documentation that describes the error. ### accountBalance Response parameters for the account balance. * `currentBalance` (_number (double)_, required) Amount that’s owed, which includes the current balance and overdue balance. Example: `240.6`. * `lastBillAmount` (_number (double)_) Last bill amount. Example: `230.1`. * `lastPaymentAmount` (_number (double)_) Last paid bill amount. Example: `130.9`. * `nextPaymentDueDate` (_date-only_) Due date for the next payment. If the due date for the next payment isn’t applicable, then no response is provided. Example: `2022-01-25`. * `overdueAmount` (_number (double)_) Unpaid previous balance amount. Example: `100.7`. * `minimumAmount` (_number (double)_) Minimum payment amount required to avoid collection action. Example: `11.8`. * `minimumPaymentDate` (_date-only_) Due date for the minimum payment to avoid collection action. Example: `2024-01-25`. * `currencyCode` (_string_) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. * `nextPaymentAmount` (_number (double)_) Amount applicable if billed but not paid. If a zero account balance is found or the amount is paid, then no response is provided. Example: `100.5`. ### billAdjustmentRequest Request parameters for bill adjustment. * `billId` (_string_) Reference to the unique external bill identifier, which is required if the adjustment reason is because of a high bill. Example: `0015f00567FpRVilpK`. * `adjustmentDate` (_date-only_) Date of request for the adjustment. The current date is the default value. Example: `2024-01-28`. * `adjustmentAmount` (_number (double)_, required) Bill adjustment amount, which is either positive or negative. Example: `9000.96`. * `adjustmentReason` (_string_, required) Reason for requesting the adjustment, such as high bill, goodwill, or compensation. Example: `High bill`. * `triggerBilling` (_boolean_) Whether to issue a bill immediately (true) or apply the bill adjustment on the next scheduled bill (false). Example: `true`. * `requestDateTime` (_datetime (rfc3339)_, required) Timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-01-28T06:28:30.000Z`. ### billRequest Parameters of the bill request. * `billDate` (_date-only_) Date to generate the bill. If the billDate property isn’t specified, the default value is the current date. Example: `2022-02-28`. * `requestReason` (_string_, required) Reason for bill generation requests, such as a regular request or rebill request. Example: `Regular`. * `billId` (_string_) Unique reference to a single bill in the billing system. The bill ID is required for rebill requests. Example: `001B000001NL5Z9IAL`. * `requestDateTime` (_datetime (rfc3339)_, required) Timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-02-27T18:39:21.000Z`. ### contract Details of the contract. * `accountId` (_string_) Unique identifier for the account in Salesforce. Example: `a3E5f000000xTx8LAF`. * `requestDateTime` (_datetime (rfc3339)_, required) Timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2024-01-25T08:30:54.814Z`. * `assets` (_array of object_) Includes all fields of `assetDetails`. ### accountHoldRequest Parameters for the account hold request. * `holdStartDate` (_date-only_) Start date of the holding period. If the holdStartDate property isn’t specified, then the current date is the default value. Example: `2024-01-28`. * `holdEndDate` (_date-only_) End date of the holding period. Example: `2024-02-28`. * `requestReason` (_string_, required) Reason to request an account on billing hold, such as high bill, complaint, or any other issue. Example: `High Bill`. * `billId` (_string_) Unique external bill identifier, which is required if the request reason is high bill. Example: `0015f00567FpRVilpK`. * `requestDateTime` (_datetime (rfc3339)_, required) Timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2024-01-28T06:12:15.000Z`. ### paymentPlan Details of the payment plan. * `accountId` (_string_) Unique identifier for the account in Salesforce. Example: `0017Ikxp9820iLtdm`. * `startDate` (_date-only_) Start date of the payment plan with the current date as the default. Example: `2022-02-28`. * `totalAmount` (_number (double)_, required) Total monetary amount covered by the payment plan. Example: `2500.76`. * `currencyCode` (_string_) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `GBP`. * `numberOfInstallments` (_integer (int)_, required) Number of recurring payments agreed upon with the customer. Example: `12`. * `initialAmount` (_integer (int)_) Initial or upfront payment amount. Example: `1900`. * `initialAmountDueDate` (_date-only_) Date by when the initial amount is must be paid. Example: `2022-02-23`. * `recurringAmount` (_number (double)_, required) Monetary amount of each recurring payment. Example: `1500.75`. * `paymentFrequency` (_string_, required) Frequency of installments, such as weekly, monthly, or quarterly. Example: `Weekly`. * `paymentMethod` (_string_, required) Mode of payment, such as check, direct debit, or credit card. Example: `Cheque`. * `paymentPlanReason` (_string_, required) Reason for the payment plan. Example: `New payment plan for updated payment method.`. * `requestDateTime` (_datetime (rfc3339)_, required) Timestamp of the request. The default value is the current date or time when the transaction is initiated. Example: `2022-02-28T01:59:58.000Z`. * `paymentPlanId` (_string_, required) Unique identifier for the payment plan in Salesforce. Example: `0017aetd9820iLxaz`. ### createCustomerContract Creates customer contracts in the billing system based on the interaction with the customer. * `id` (_string_) ID of the contract item. Example: `a3E5f000000xT627nay`. * `salesforceId` (_string_, required) ID of the contract as stored in Salesforce. Example: `a3E5f000000xT627nay`. * `customerId` (_string_, required) Unique identifier of the customer. Example: `a3E5f000000xTx8LAF`. * `accountId` (_string_, required) Unique billing account ID. Example: `wjoEKDM983`. * `activationDate` (_date-only_, required) Activation date of the energy service agreement. Example: `2022-02-28`. * `billingSchedule` (_string_) Billing schedule of the customer contract. Example: `weekly`. * `product` (_object_, required) Product in the billing system. Includes all fields of `createProduct`. * `status` (_string_) Service status. Example: `Active`. * `startDate` (_date-only_, required) Start date of service. Example: `2024-02-28`. * `endDate` (_date-only_) End date of service. Example: `2024-02-28`. * `type` (_string_, required) Service type. Example: `Gas`. * `statusReason` (_string_) Reason for the current customer contract status. Example: `Inactive because of dues`. * `statusChangeDate` (_date-only_) Date when the status was changed. Example: `2022-02-28`. * `contractItems` (_array of object_) Includes all fields of `createCustomerContractItem`. ### updateCustomerContract Updates customer contracts in the billing system based on the interaction with the customer. * `id` (_string_, required) ID of the contract item. Example: `a3E5f000000xT627nay`. * `salesforceId` (_string_, required) ID of the contract as stored in Salesforce. Example: `a3E5f000000xT627nay`. * `customerId` (_string_, required) Unique identifier of the customer. Example: `a3E5f000000xTx8LAF`. * `accountId` (_string_, required) Unique billing account ID. Example: `wjoEKDM983`. * `activationDate` (_date-only_, required) Activation date of the energy service agreement. Example: `2024-02-28`. * `billingSchedule` (_string_, required) Billing schedule of the customer contract. Example: `weekly`. * `product` (_object_, required) Product in the billing system. Includes all fields of `createProduct`. * `status` (_string_, required) Service status. Example: `Active`. * `startDate` (_date-only_, required) Start date of service. Example: `2024-02-28`. * `endDate` (_date-only_, required) End date of service. Example: `2024-02-28`. * `type` (_string_, required) Service type. Example: `Gas`. * `statusReason` (_string_, required) Reason for the current customer contract status. Example: `Inactive because account is past due.`. * `statusChangeDate` (_date-only_, required) Date when the status was changed. Example: `2024-02-28`. * `contractItems` (_array of object_, required) Includes all fields of `updateCustomerContractItem`. ### patchCustomerContract Updates customer contracts in the billing system based on the interaction with the customer. * `op` (_string_, required) Operation to perform for the contract. Example: `replace`. * `attributeItems` (_array of object_, required) Array of the field and value to update for the contract. Includes all fields of `patchContractAttributeItem`. ### createCustomerContractItem Creates customer contract items in the billing system based on the interaction with the customer. * `id` (_string_) ID of the contract item. Example: `a3E5f000000xT627nay`. * `salesforceId` (_string_, required) ID of the contract as stored in Salesforce. Example: `a3E5f000000xT627nay`. * `account` (_string_) Unique billing account ID. Example: `a3E5f000000xTx8LAF`. * `contractId` (_string_) ID of the contract in the billing system. Example: `wjoEKDM983`. * `product` (_object_) Product in the billing system. Includes all fields of `createProduct`. * `locationId` (_string_) ID of the location. Example: `E-BS93214`. * `servicePointId` (_string_) Unique identifier of the service point in Salesforce. Example: `E-ED9871617`. * `startDate` (_date-only_) Start date of service. Example: `2022-02-28`. * `endDate` (_date-only_) End date of service. Example: `2022-02-28`. * `oneTimeCharge` (_string_) One-time charge of the asset. Example: `17`. * `recurringCharge` (_string_) Cyclic charges of the asset. Example: `189`. * `recurringPricePeriod` (_string_) Period during which the recurring price is scheduled for the product. Example: `189`. * `usagePeriod` (_string_) Usage period of the service point. Example: `189`. * `usageQuantity` (_string_) Usage quantity of the service point. Example: `189`. * `usageCharge` (_string_) Usage-based price of the asset. Example: `189`. * `usageUnitofMeasure` (_string_) Unit of measure for the usage. Example: `189`. ### updateCustomerContractItem Customer contract items in the billing system based on the interaction with the customer. * `id` (_string_, required) ID of the contract item. Example: `a3E5f000000xT627nay`. * `salesforceId` (_string_, required) ID of the contract as stored in Salesforce. Example: `a3E5f000000xT627nay`. * `account` (_string_, required) Unique billing account ID. Example: `a3E5f000000xTx8LAF`. * `contractId` (_string_, required) ID of the contract in the billing system. Example: `wjoEKDM983`. * `product` (_object_, required) Product in the billing system. Includes all fields of `createProduct`. * `locationId` (_string_, required) ID of the location. Example: `E-BS93214`. * `servicePointId` (_string_, required) Unique identifier of the service point in Salesforce. Example: `E-ED9871617`. * `startDate` (_date-only_, required) Start date of service. Example: `2024-02-28`. * `endDate` (_date-only_, required) End date of service. Example: `2024-02-28`. * `oneTimeCharge` (_string_, required) One-time charge of the asset. Example: `17`. * `recurringCharge` (_string_, required) Cyclic charges of the asset. Example: `189`. * `recurringPricePeriod` (_string_, required) Period during which the recurring price is scheduled for the product. Example: `189`. * `usagePeriod` (_string_, required) Usage period of the service point. Example: `189`. * `usageQuantity` (_string_, required) Usage quantity of the service point. Example: `189`. * `usageCharge` (_string_, required) Usage price. Example: `189`. * `usageUnitofMeasure` (_string_, required) Unit of measure for the usage. Example: `189`. ### servicePointsRequest Fetches service points for a given address. * `street` (_string_, required) Street of the address. Example: `41 Main St`. * `state` (_string_, required) State of the address. Example: `CA`. * `postalCode` (_string_, required) Postal Code of the address. Example: `95110`. * `city` (_string_, required) City of the address. Example: `San Jose`. * `country` (_string_, required) Country of the address. Example: `USA`. ### assetDetails Request to create the contracts. * `assetName` (_string_, required) Name of the asset. Example: `Southern Region Electricity`. * `parentAsset` (_string_) Name of the parent asset. If the parentAsset property isn’t specified, then the parent asset is the highest level product that was sold. Example: `Head Office Electricity`. * `productCode` (_string_) Unique product identifier. Example: `IP234`. * `productDescription` (_string_) Product name or the cost component name if the parent asset is also available. Example: `connection of broadband`. * `servicePoint` (_string_) Name of the service point. Example: `E-BS93214`. * `status` (_string_) Status of the asset. Example: `Active`. * `recurringCharge` (_number (double)_) Cyclic charges of the asset. Example: `30`. * `oneTimeCharge` (_number (double)_) One-time charge of the asset. Example: `190`. * `usageCharge` (_number (double)_) Usage-based price of the asset. Example: `17`. * `assetId` (_string_, required) Unique identifier for the asset in Salesforce. Example: `a3E5f000000xTx8LAF`. * `currencyCode` (_string_) Currency mnemonic specified for the price, which follows the ISO 4217:2015 standard. Example: `USD`. ### createProduct Specifies the request to create the product. * `id` (_string_) Specifies the external identifier of a product in the billing system. Example: `a3E5f000000xTx8LAF`. * `salesforceId` (_string_) The identifier of a product in the billing system. Example: `a3E5f000000xT627`. * `physicalProductId` (_string_) A reference to the product of physical goods. Example: `a3E5f000000xT627`. ### patchContractAttributeItem Field value to update for the contract. * `path` (_string_, required) Field to update on the contract. Example: `Contract.status`. * `value` (_string_, required) Value for the field to update on the contract. Example: `Terminated`.