REST API Reference for Billing Care

Allocate a Payment to Bills

post

/bcws/webresources/v1.0/allocations/payment/{id}/bills

Allocates a payment to one or more bills that you specify.

Request

Path Parameters

id(required): string

The ID of the payment to allocate.

Supported Media Types

application/xml
application/json

The list of bills containing an allocated amount, the account ID, and the bill unit ID. The minimum required parameter are:

amount
id

Root Schema : schema

Type: array

Show Source

Array of: object bill

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/Bill"
    }
}

Nested Schema : bill

Type: object

Show Source

accountRef: object ResourceRef
adjusted: number

The amount on the bill that was adjusted.
amount: number

The amount to be allocated.
arActionsAmtExcludingPayments: number

The total of all accounts receivable actions applied toward the bill, excluding any payments.
arBillinfoRef: object ResourceRef
billDisputed: boolean

Whether the bill includes a disputed item (true) or not (false).
billInfoId: string

The ID of the bill unit associated with the bill.
billNo: string

The bill number.
billPaidDate(required): string (date-time)

The date and time the bill was paid.
billUnitRef: object ResourceRef
creationDate(required): string (date-time)

The date and time the bill was created.
currency: integer (int32)

The type of currency associated with the bill.
currentTotal: number

The current total of the bill.
cycleEnds: string (date-time)

The date and time the billing cycle ends.
cycleStarts: string (date-time)

The date and time the billing cycle starts.
disputed: number

The amount in the bill that is in dispute.
due: number

The amount due for the bill.
dueDate: string (date-time)

The date and time the bill is due.
extension: object extension

The extended attributes.
hierarchySize: integer (int32)

The number of bills in a hierarchy.
id(required): string

The ID.
name: string

he name of the bill.
originalBillNo: string

The bill number associated with the original bill.
parent: object ResourceRef
parentAccountRef: object ResourceRef
parentCompanyName(required): string

The company name of the parent associated with the bill.
parentFirstName: string

The first name of the parent associated with the bill.
parentLastName: string

The last name of the parent associated with the bill.
parentSalutation(required): string

The title of the parent associated with the bill.
previousTotal: number

The previous total for the bill.
receivedForBill: number

The payment amount received for the bill.
recurringCharges: number

The total amount of all recurring charges in the bill.
subordsTotal: number

The total amount from all subordinates, if the bill is a parent in a billing hierarchy.
totalDue: number

The total due for the bill.
transfered: number

The amount in the bill that has been transferred.
writeoff: number

The amount in the bill that has been written off.

{
    "required":[
        "billPaidDate",
        "creationDate",
        "id",
        "parentCompanyName",
        "parentSalutation"
    ],
    "type":"object",
    "properties":{
        "extension":{
            "type":"object",
            "description":"The extended attributes."
        },
        "id":{
            "type":"string",
            "description":"The ID."
        },
        "accountRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "adjusted":{
            "type":"number",
            "description":"The amount on the bill that was adjusted."
        },
        "arBillinfoRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "billUnitRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "billNo":{
            "type":"string",
            "description":"The bill number."
        },
        "creationDate":{
            "type":"string",
            "description":"The date and time the bill was created.",
            "format":"date-time"
        },
        "currency":{
            "type":"integer",
            "description":"The type of currency associated with the bill.",
            "format":"int32"
        },
        "disputed":{
            "type":"number",
            "description":"The amount in the bill that is in dispute."
        },
        "currentTotal":{
            "type":"number",
            "description":"The current total of the bill."
        },
        "due":{
            "type":"number",
            "description":"The amount due for the bill."
        },
        "previousTotal":{
            "type":"number",
            "description":"The previous total for the bill."
        },
        "totalDue":{
            "type":"number",
            "description":"The total due for the bill."
        },
        "receivedForBill":{
            "type":"number",
            "description":"The payment amount received for the bill."
        },
        "arActionsAmtExcludingPayments":{
            "type":"number",
            "description":"The total of all accounts receivable actions applied toward the bill, excluding any payments."
        },
        "dueDate":{
            "type":"string",
            "description":"The date and time the bill is due.",
            "format":"date-time"
        },
        "cycleEnds":{
            "type":"string",
            "description":"The date and time the billing cycle ends.",
            "format":"date-time"
        },
        "name":{
            "type":"string",
            "description":"he name of the bill."
        },
        "parent":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "hierarchySize":{
            "type":"integer",
            "description":"The number of bills in a hierarchy.",
            "format":"int32"
        },
        "parentAccountRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "parentFirstName":{
            "type":"string",
            "description":"The first name of the parent associated with the bill."
        },
        "parentLastName":{
            "type":"string",
            "description":"The last name of the parent associated with the bill."
        },
        "parentCompanyName":{
            "type":"string",
            "description":"The company name of the parent associated with the bill."
        },
        "parentSalutation":{
            "type":"string",
            "description":"The title of the parent associated with the bill."
        },
        "cycleStarts":{
            "type":"string",
            "description":"The date and time the billing cycle starts.",
            "format":"date-time"
        },
        "subordsTotal":{
            "type":"number",
            "description":"The total amount from all subordinates, if the bill is a parent in a billing hierarchy."
        },
        "transfered":{
            "type":"number",
            "description":"The amount in the bill that has been transferred."
        },
        "writeoff":{
            "type":"number",
            "description":"The amount in the bill that has been written off."
        },
        "amount":{
            "type":"number",
            "description":"The amount to be allocated."
        },
        "billInfoId":{
            "type":"string",
            "description":"The ID of the bill unit associated with the bill."
        },
        "billPaidDate":{
            "type":"string",
            "description":"The date and time the bill was paid.",
            "format":"date-time"
        },
        "recurringCharges":{
            "type":"number",
            "description":"The total amount of all recurring charges in the bill."
        },
        "billDisputed":{
            "type":"boolean",
            "description":"Whether the bill includes a disputed item (<b>true</b>) or not (<b>false</b>)."
        },
        "originalBillNo":{
            "type":"string",
            "description":"The bill number associated with the original bill."
        }
    },
    "xml":{
        "name":"bill"
    }
}

Nested Schema : ResourceRef

Type: object

Show Source

id(required): string

The ID.
uri: string

The Uniform Resource Identifier (URI) associated with the resource.

{
    "required":[
        "id"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The ID."
        },
        "uri":{
            "type":"string",
            "description":"The Uniform Resource Identifier (URI) associated with the resource."
        }
    }
}

Nested Schema : extension

Type: object

The extended attributes.

The list of bills containing an allocated amount, the account ID, and the bill unit ID. The minimum required parameter are:

amount
id

Root Schema : schema

Type: array

Show Source

Array of: object bill

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/Bill"
    }
}

Nested Schema : bill

Type: object

Show Source

accountRef: object ResourceRef
adjusted: number

The amount on the bill that was adjusted.
amount: number

The amount to be allocated.
arActionsAmtExcludingPayments: number

The total of all accounts receivable actions applied toward the bill, excluding any payments.
arBillinfoRef: object ResourceRef
billDisputed: boolean

Whether the bill includes a disputed item (true) or not (false).
billInfoId: string

The ID of the bill unit associated with the bill.
billNo: string

The bill number.
billPaidDate(required): string (date-time)

The date and time the bill was paid.
billUnitRef: object ResourceRef
creationDate(required): string (date-time)

The date and time the bill was created.
currency: integer (int32)

The type of currency associated with the bill.
currentTotal: number

The current total of the bill.
cycleEnds: string (date-time)

The date and time the billing cycle ends.
cycleStarts: string (date-time)

The date and time the billing cycle starts.
disputed: number

The amount in the bill that is in dispute.
due: number

The amount due for the bill.
dueDate: string (date-time)

The date and time the bill is due.
extension: object extension

The extended attributes.
hierarchySize: integer (int32)

The number of bills in a hierarchy.
id(required): string

The ID.
name: string

he name of the bill.
originalBillNo: string

The bill number associated with the original bill.
parent: object ResourceRef
parentAccountRef: object ResourceRef
parentCompanyName(required): string

The company name of the parent associated with the bill.
parentFirstName: string

The first name of the parent associated with the bill.
parentLastName: string

The last name of the parent associated with the bill.
parentSalutation(required): string

The title of the parent associated with the bill.
previousTotal: number

The previous total for the bill.
receivedForBill: number

The payment amount received for the bill.
recurringCharges: number

The total amount of all recurring charges in the bill.
subordsTotal: number

The total amount from all subordinates, if the bill is a parent in a billing hierarchy.
totalDue: number

The total due for the bill.
transfered: number

The amount in the bill that has been transferred.
writeoff: number

The amount in the bill that has been written off.

{
    "required":[
        "billPaidDate",
        "creationDate",
        "id",
        "parentCompanyName",
        "parentSalutation"
    ],
    "type":"object",
    "properties":{
        "extension":{
            "type":"object",
            "description":"The extended attributes."
        },
        "id":{
            "type":"string",
            "description":"The ID."
        },
        "accountRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "adjusted":{
            "type":"number",
            "description":"The amount on the bill that was adjusted."
        },
        "arBillinfoRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "billUnitRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "billNo":{
            "type":"string",
            "description":"The bill number."
        },
        "creationDate":{
            "type":"string",
            "description":"The date and time the bill was created.",
            "format":"date-time"
        },
        "currency":{
            "type":"integer",
            "description":"The type of currency associated with the bill.",
            "format":"int32"
        },
        "disputed":{
            "type":"number",
            "description":"The amount in the bill that is in dispute."
        },
        "currentTotal":{
            "type":"number",
            "description":"The current total of the bill."
        },
        "due":{
            "type":"number",
            "description":"The amount due for the bill."
        },
        "previousTotal":{
            "type":"number",
            "description":"The previous total for the bill."
        },
        "totalDue":{
            "type":"number",
            "description":"The total due for the bill."
        },
        "receivedForBill":{
            "type":"number",
            "description":"The payment amount received for the bill."
        },
        "arActionsAmtExcludingPayments":{
            "type":"number",
            "description":"The total of all accounts receivable actions applied toward the bill, excluding any payments."
        },
        "dueDate":{
            "type":"string",
            "description":"The date and time the bill is due.",
            "format":"date-time"
        },
        "cycleEnds":{
            "type":"string",
            "description":"The date and time the billing cycle ends.",
            "format":"date-time"
        },
        "name":{
            "type":"string",
            "description":"he name of the bill."
        },
        "parent":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "hierarchySize":{
            "type":"integer",
            "description":"The number of bills in a hierarchy.",
            "format":"int32"
        },
        "parentAccountRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "parentFirstName":{
            "type":"string",
            "description":"The first name of the parent associated with the bill."
        },
        "parentLastName":{
            "type":"string",
            "description":"The last name of the parent associated with the bill."
        },
        "parentCompanyName":{
            "type":"string",
            "description":"The company name of the parent associated with the bill."
        },
        "parentSalutation":{
            "type":"string",
            "description":"The title of the parent associated with the bill."
        },
        "cycleStarts":{
            "type":"string",
            "description":"The date and time the billing cycle starts.",
            "format":"date-time"
        },
        "subordsTotal":{
            "type":"number",
            "description":"The total amount from all subordinates, if the bill is a parent in a billing hierarchy."
        },
        "transfered":{
            "type":"number",
            "description":"The amount in the bill that has been transferred."
        },
        "writeoff":{
            "type":"number",
            "description":"The amount in the bill that has been written off."
        },
        "amount":{
            "type":"number",
            "description":"The amount to be allocated."
        },
        "billInfoId":{
            "type":"string",
            "description":"The ID of the bill unit associated with the bill."
        },
        "billPaidDate":{
            "type":"string",
            "description":"The date and time the bill was paid.",
            "format":"date-time"
        },
        "recurringCharges":{
            "type":"number",
            "description":"The total amount of all recurring charges in the bill."
        },
        "billDisputed":{
            "type":"boolean",
            "description":"Whether the bill includes a disputed item (<b>true</b>) or not (<b>false</b>)."
        },
        "originalBillNo":{
            "type":"string",
            "description":"The bill number associated with the original bill."
        }
    },
    "xml":{
        "name":"bill"
    }
}

Nested Schema : ResourceRef

Type: object

Show Source

id(required): string

The ID.
uri: string

The Uniform Resource Identifier (URI) associated with the resource.

{
    "required":[
        "id"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The ID."
        },
        "uri":{
            "type":"string",
            "description":"The Uniform Resource Identifier (URI) associated with the resource."
        }
    }
}

Nested Schema : extension

Type: object

The extended attributes.

Response

201 Response

The payment was allocated to the bills successfully.

500 Response

An internal server error occurred

Examples

This example shows how to allocate a payment to bills by submitting a POST request on the REST resource using cURL. For more information about cURL, see "Use cURL".

cURL Command

curl -X POST 'http://hostname:port/bcws/webresources/version/allocations/payment/0.0.0.1+-item-payment+128048/bills' -H 'content-type: application/json' -d @allocateToBill.json

where:

hostname is the URL for the Billing Care REST server.
port is the port for the Billing Care REST server.
version is the version of the API you're using, such as v1.0.
allocateToBill.json is the JSON file that specifies how to allocate the payment.

Example of Request Body

This example shows the contents of the allocateToBill.json file sent as the request body.

[
  {
    "extension": null,
    "id": "0.0.0.1+-bill+200506",
    "accountRef": {
      "id": "0.0.0.1+-account+81329",
      "uri": null
    },
    "adjusted": -0.5,
    "arBillinfoRef": {
      "id": "0.0.0.1+-billinfo+78769",
      "uri": null
    },
    "billUnitRef": {
      "id": "0.0.0.1+-billinfo+78769",
      "uri": null
    },
    "billNo": "B1-641",
    "creationDate": null,
    "currency": null,
    "disputed": 0,
    "currentTotal": 22.95,
    "due": 22.45,
    "previousTotal": -1341.73,
    "totalDue": 22.95,
    "receivedForBill": 0,
    "arActionsAmtExcludingPayments": -0.5,
    "cycleEnds": 1607673600000,
    "name": null,
    "parent": null,
    "hierarchySize": 0,
    "parentAccountRef": null,
    "parentFirstName": null,
    "parentLastName": null,
    "parentCompanyName": null,
    "parentSalutation": null,
    "cycleStarts": 1605081600000,
    "subordsTotal": 0,
    "transfered": 0,
    "writeoff": 0,
    "amount": 0.5,
    "billInfoId": "Bill Unit(1)",
    "billPaidDate": 0,
    "recurringCharges": null,
    "billDisputed": null,
    "originalBillNo": null
  }
]

Example of Response Body

If successful, the response code 204 is returned with no response body.