REST API Reference for Billing Care

Create an Installment Schedule

post

/bcws/webresources/v1.0/installmentManagement/installmentSchedule

Creates an installment schedule.

Request

There are no request parameters for this operation.

Supported Media Types

application/xml
application/json

The installment schedule to create. The minimum required parameters are:

customerRef
validFor
scheduleSpecRef
totalAmount
bills
installments

Root Schema : schema

Type: object

Show Source

billPreference: integer (int32)
Indicates either to bill the installment amount immediately or to keep it open and include it with the customer's billing cycle. Allowed Values:
- 0 (Auto-align)
- 1 (Immediate)
billProfileRef(required): string

The customer bill unit reference.
bills(required): array bills
channel(required): string

The source of the request, for example the name of the store or app. For future use.
chargeOfferRef(required): string

The charge offer reference. For future use.
code(required): string

Placeholder for the external code.
createdAt(required): string

The date of creation.
customerRef(required): string

The customer account reference.
descr(required): string

The installment schedule description.
expiresAt(required): string

The expiration date.
glid(required): string

The general ledger ID for the installment charge.
href(required): string

The unique resource URL, used for getting the object.
id(required): string

The installment schedule's ID.
installmentAmount: object Money
installmentPeriod(required): string

The installment cycle. For future use. Allowed Values: ANNUAL, SEMI-ANNUAL, QUARTERLY, MONTHLY, WEEKLY, DAILY. Default Value: MONTHLY
installments(required): array installments
installmentType(required): string

The installment type. Allowed Values: EQUAL INSTALLMENT, NON-EQUAL INSTALLMENT
lastInstallmentAt(required): string

The last installment date. For future use.
modifiedAt(required): string

The last updated date.
name(required): string

The installment schedule name.
nextInstallmentAt(required): string

The next installment date. For future use.
scheduleSpecRef(required): string

The installment schedule specification reference.
serviceRef(required): string

The service reference.
startsAt(required): string

The start date.
status: integer (int32)
The installment schedule status. Allowed Values:
- 100 (Open)
- 101 (Charged)
- 102 (Paid)
- 103 (Broken)
- 104 (Canceled)
- 105 (Finished)
totalAmount: object Money
totalDue: object Money
totalInstallments: integer (int32)

The total number of installments.
validFor: object TimePeriod

{
    "required":[
        "billProfileRef",
        "bills",
        "channel",
        "chargeOfferRef",
        "code",
        "createdAt",
        "customerRef",
        "descr",
        "expiresAt",
        "glid",
        "href",
        "id",
        "installmentPeriod",
        "installmentType",
        "installments",
        "lastInstallmentAt",
        "modifiedAt",
        "name",
        "nextInstallmentAt",
        "scheduleSpecRef",
        "serviceRef",
        "startsAt"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The installment schedule's ID."
        },
        "href":{
            "type":"string",
            "description":"The unique resource URL, used for getting the object."
        },
        "descr":{
            "type":"string",
            "description":"The installment schedule description."
        },
        "createdAt":{
            "type":"string",
            "description":"The date of creation."
        },
        "modifiedAt":{
            "type":"string",
            "description":"The last updated date."
        },
        "startsAt":{
            "type":"string",
            "description":"The start date."
        },
        "expiresAt":{
            "type":"string",
            "description":"The expiration date."
        },
        "code":{
            "type":"string",
            "description":"Placeholder for the external code."
        },
        "name":{
            "type":"string",
            "description":"The installment schedule name."
        },
        "billProfileRef":{
            "type":"string",
            "description":"The customer bill unit reference."
        },
        "status":{
            "type":"integer",
            "description":"The installment schedule status. Allowed Values: <ul><li><b>100</b> (Open)</li><li><b>101</b> (Charged)</li><li><b>102</b> (Paid)</li><li><b>103</b> (Broken)</li><li><b>104</b> (Canceled)</li><li><b>105</b> (Finished)</li></ul>",
            "format":"int32"
        },
        "lastInstallmentAt":{
            "type":"string",
            "description":"The last installment date. For future use."
        },
        "nextInstallmentAt":{
            "type":"string",
            "description":"The next installment date. For future use."
        },
        "installmentType":{
            "type":"string",
            "description":"The installment type. Allowed Values: EQUAL INSTALLMENT, NON-EQUAL INSTALLMENT"
        },
        "billPreference":{
            "type":"integer",
            "description":"Indicates either to bill the installment amount immediately or to keep it open and include it with the customer's billing cycle. Allowed Values: <ul><li><b>0</b> (Auto-align)</li><li><b>1</b> (Immediate)</li></ul>",
            "format":"int32"
        },
        "installmentPeriod":{
            "type":"string",
            "description":"The installment cycle. For future use. Allowed Values: ANNUAL, SEMI-ANNUAL, QUARTERLY, MONTHLY, WEEKLY, DAILY.  Default Value: MONTHLY"
        },
        "totalAmount":{
            "$ref":"#/components/schemas/Money"
        },
        "totalDue":{
            "$ref":"#/components/schemas/Money"
        },
        "totalInstallments":{
            "type":"integer",
            "description":"The total number of installments.",
            "format":"int32"
        },
        "installmentAmount":{
            "$ref":"#/components/schemas/Money"
        },
        "customerRef":{
            "type":"string",
            "description":"The customer account reference."
        },
        "serviceRef":{
            "type":"string",
            "description":"The service reference."
        },
        "chargeOfferRef":{
            "type":"string",
            "description":"The charge offer reference. For future use."
        },
        "glid":{
            "type":"string",
            "description":"The general ledger ID for the installment charge."
        },
        "channel":{
            "type":"string",
            "description":"The source of the request, for example the name of the store or app. For future use."
        },
        "scheduleSpecRef":{
            "type":"string",
            "description":"The installment schedule specification reference."
        },
        "installments":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/Installment"
            }
        },
        "bills":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/InstallmentScheduleBills"
            }
        },
        "validFor":{
            "$ref":"#/components/schemas/TimePeriod"
        }
    },
    "xml":{
        "name":"installmentSchedule"
    }
}

Nested Schema : bills

Type: array

Show Source

Array of: object InstallmentScheduleBills

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

Nested Schema : Money

Type: object

Show Source

amount(required): number

The amount of money.
currency: integer (int32)

The currency for the money.

{
    "required":[
        "amount"
    ],
    "type":"object",
    "properties":{
        "amount":{
            "type":"number",
            "description":"The amount of money."
        },
        "currency":{
            "type":"integer",
            "description":"The currency for the money.",
            "format":"int32"
        }
    }
}

Nested Schema : installments

Type: array

Show Source

Array of: object Installment

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

Nested Schema : TimePeriod

Type: object

Show Source

endDateTime(required): string
startDateTime(required): string

{
    "required":[
        "endDateTime",
        "startDateTime"
    ],
    "type":"object",
    "properties":{
        "startDateTime":{
            "type":"string"
        },
        "endDateTime":{
            "type":"string"
        }
    }
}

Nested Schema : InstallmentScheduleBills

Type: object

Show Source

billId(required): string

The installment schedule bill ID.

{
    "required":[
        "billId"
    ],
    "type":"object",
    "properties":{
        "billId":{
            "type":"string",
            "description":"The installment schedule bill ID."
        }
    }
}

Nested Schema : Installment

Type: object

Show Source

amount: object Money
createdAt(required): string

TThe date of creation.
customerRef(required): string

The customer reference.
descr(required): string

The installment description.
dueDate(required): string

The date of installment collection/charge.
href(required): string

The unique resource URL, used for getting the object.
id(required): string

The installment's ID.
scheduleRef(required): string

The reference to the installment schedule.
status: integer (int32)
The installment status. Allowed Values:
- 100 (Open)
- 101 (Charged)
- 102 (Paid)
- 103 (Broken)
- 104 (Canceled)
- 105 (Finished)

{
    "required":[
        "createdAt",
        "customerRef",
        "descr",
        "dueDate",
        "href",
        "id",
        "scheduleRef"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The installment's ID."
        },
        "href":{
            "type":"string",
            "description":"The unique resource URL, used for getting the object."
        },
        "createdAt":{
            "type":"string",
            "description":"TThe date of creation."
        },
        "descr":{
            "type":"string",
            "description":"The installment description."
        },
        "status":{
            "type":"integer",
            "description":"The installment status. Allowed Values: <ul><li><b>100</b> (Open)</li><li><b>101</b> (Charged)</li><li><b>102</b> (Paid)</li><li><b>103</b> (Broken)</li><li><b>104</b> (Canceled)</li><li><b>105</b> (Finished)</li></ul>",
            "format":"int32"
        },
        "dueDate":{
            "type":"string",
            "description":"The date of installment collection/charge."
        },
        "amount":{
            "$ref":"#/components/schemas/Money"
        },
        "scheduleRef":{
            "type":"string",
            "description":"The reference to the installment schedule."
        },
        "customerRef":{
            "type":"string",
            "description":"The customer reference."
        }
    }
}

The installment schedule to create. The minimum required parameters are:

customerRef
validFor
scheduleSpecRef
totalAmount
bills
installments

Root Schema : schema

Type: object

Show Source

billPreference: integer (int32)
Indicates either to bill the installment amount immediately or to keep it open and include it with the customer's billing cycle. Allowed Values:
- 0 (Auto-align)
- 1 (Immediate)
billProfileRef(required): string

The customer bill unit reference.
bills(required): array bills
channel(required): string

The source of the request, for example the name of the store or app. For future use.
chargeOfferRef(required): string

The charge offer reference. For future use.
code(required): string

Placeholder for the external code.
createdAt(required): string

The date of creation.
customerRef(required): string

The customer account reference.
descr(required): string

The installment schedule description.
expiresAt(required): string

The expiration date.
glid(required): string

The general ledger ID for the installment charge.
href(required): string

The unique resource URL, used for getting the object.
id(required): string

The installment schedule's ID.
installmentAmount: object Money
installmentPeriod(required): string

The installment cycle. For future use. Allowed Values: ANNUAL, SEMI-ANNUAL, QUARTERLY, MONTHLY, WEEKLY, DAILY. Default Value: MONTHLY
installments(required): array installments
installmentType(required): string

The installment type. Allowed Values: EQUAL INSTALLMENT, NON-EQUAL INSTALLMENT
lastInstallmentAt(required): string

The last installment date. For future use.
modifiedAt(required): string

The last updated date.
name(required): string

The installment schedule name.
nextInstallmentAt(required): string

The next installment date. For future use.
scheduleSpecRef(required): string

The installment schedule specification reference.
serviceRef(required): string

The service reference.
startsAt(required): string

The start date.
status: integer (int32)
The installment schedule status. Allowed Values:
- 100 (Open)
- 101 (Charged)
- 102 (Paid)
- 103 (Broken)
- 104 (Canceled)
- 105 (Finished)
totalAmount: object Money
totalDue: object Money
totalInstallments: integer (int32)

The total number of installments.
validFor: object TimePeriod

{
    "required":[
        "billProfileRef",
        "bills",
        "channel",
        "chargeOfferRef",
        "code",
        "createdAt",
        "customerRef",
        "descr",
        "expiresAt",
        "glid",
        "href",
        "id",
        "installmentPeriod",
        "installmentType",
        "installments",
        "lastInstallmentAt",
        "modifiedAt",
        "name",
        "nextInstallmentAt",
        "scheduleSpecRef",
        "serviceRef",
        "startsAt"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The installment schedule's ID."
        },
        "href":{
            "type":"string",
            "description":"The unique resource URL, used for getting the object."
        },
        "descr":{
            "type":"string",
            "description":"The installment schedule description."
        },
        "createdAt":{
            "type":"string",
            "description":"The date of creation."
        },
        "modifiedAt":{
            "type":"string",
            "description":"The last updated date."
        },
        "startsAt":{
            "type":"string",
            "description":"The start date."
        },
        "expiresAt":{
            "type":"string",
            "description":"The expiration date."
        },
        "code":{
            "type":"string",
            "description":"Placeholder for the external code."
        },
        "name":{
            "type":"string",
            "description":"The installment schedule name."
        },
        "billProfileRef":{
            "type":"string",
            "description":"The customer bill unit reference."
        },
        "status":{
            "type":"integer",
            "description":"The installment schedule status. Allowed Values: <ul><li><b>100</b> (Open)</li><li><b>101</b> (Charged)</li><li><b>102</b> (Paid)</li><li><b>103</b> (Broken)</li><li><b>104</b> (Canceled)</li><li><b>105</b> (Finished)</li></ul>",
            "format":"int32"
        },
        "lastInstallmentAt":{
            "type":"string",
            "description":"The last installment date. For future use."
        },
        "nextInstallmentAt":{
            "type":"string",
            "description":"The next installment date. For future use."
        },
        "installmentType":{
            "type":"string",
            "description":"The installment type. Allowed Values: EQUAL INSTALLMENT, NON-EQUAL INSTALLMENT"
        },
        "billPreference":{
            "type":"integer",
            "description":"Indicates either to bill the installment amount immediately or to keep it open and include it with the customer's billing cycle. Allowed Values: <ul><li><b>0</b> (Auto-align)</li><li><b>1</b> (Immediate)</li></ul>",
            "format":"int32"
        },
        "installmentPeriod":{
            "type":"string",
            "description":"The installment cycle. For future use. Allowed Values: ANNUAL, SEMI-ANNUAL, QUARTERLY, MONTHLY, WEEKLY, DAILY.  Default Value: MONTHLY"
        },
        "totalAmount":{
            "$ref":"#/components/schemas/Money"
        },
        "totalDue":{
            "$ref":"#/components/schemas/Money"
        },
        "totalInstallments":{
            "type":"integer",
            "description":"The total number of installments.",
            "format":"int32"
        },
        "installmentAmount":{
            "$ref":"#/components/schemas/Money"
        },
        "customerRef":{
            "type":"string",
            "description":"The customer account reference."
        },
        "serviceRef":{
            "type":"string",
            "description":"The service reference."
        },
        "chargeOfferRef":{
            "type":"string",
            "description":"The charge offer reference. For future use."
        },
        "glid":{
            "type":"string",
            "description":"The general ledger ID for the installment charge."
        },
        "channel":{
            "type":"string",
            "description":"The source of the request, for example the name of the store or app. For future use."
        },
        "scheduleSpecRef":{
            "type":"string",
            "description":"The installment schedule specification reference."
        },
        "installments":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/Installment"
            }
        },
        "bills":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/InstallmentScheduleBills"
            }
        },
        "validFor":{
            "$ref":"#/components/schemas/TimePeriod"
        }
    },
    "xml":{
        "name":"installmentSchedule"
    }
}

Nested Schema : bills

Type: array

Show Source

Array of: object InstallmentScheduleBills

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

Nested Schema : Money

Type: object

Show Source

amount(required): number

The amount of money.
currency: integer (int32)

The currency for the money.

{
    "required":[
        "amount"
    ],
    "type":"object",
    "properties":{
        "amount":{
            "type":"number",
            "description":"The amount of money."
        },
        "currency":{
            "type":"integer",
            "description":"The currency for the money.",
            "format":"int32"
        }
    }
}

Nested Schema : installments

Type: array

Show Source

Array of: object Installment

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

Nested Schema : TimePeriod

Type: object

Show Source

endDateTime(required): string
startDateTime(required): string

{
    "required":[
        "endDateTime",
        "startDateTime"
    ],
    "type":"object",
    "properties":{
        "startDateTime":{
            "type":"string"
        },
        "endDateTime":{
            "type":"string"
        }
    }
}

Nested Schema : InstallmentScheduleBills

Type: object

Show Source

billId(required): string

The installment schedule bill ID.

{
    "required":[
        "billId"
    ],
    "type":"object",
    "properties":{
        "billId":{
            "type":"string",
            "description":"The installment schedule bill ID."
        }
    }
}

Nested Schema : Installment

Type: object

Show Source

amount: object Money
createdAt(required): string

TThe date of creation.
customerRef(required): string

The customer reference.
descr(required): string

The installment description.
dueDate(required): string

The date of installment collection/charge.
href(required): string

The unique resource URL, used for getting the object.
id(required): string

The installment's ID.
scheduleRef(required): string

The reference to the installment schedule.
status: integer (int32)
The installment status. Allowed Values:
- 100 (Open)
- 101 (Charged)
- 102 (Paid)
- 103 (Broken)
- 104 (Canceled)
- 105 (Finished)

{
    "required":[
        "createdAt",
        "customerRef",
        "descr",
        "dueDate",
        "href",
        "id",
        "scheduleRef"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The installment's ID."
        },
        "href":{
            "type":"string",
            "description":"The unique resource URL, used for getting the object."
        },
        "createdAt":{
            "type":"string",
            "description":"TThe date of creation."
        },
        "descr":{
            "type":"string",
            "description":"The installment description."
        },
        "status":{
            "type":"integer",
            "description":"The installment status. Allowed Values: <ul><li><b>100</b> (Open)</li><li><b>101</b> (Charged)</li><li><b>102</b> (Paid)</li><li><b>103</b> (Broken)</li><li><b>104</b> (Canceled)</li><li><b>105</b> (Finished)</li></ul>",
            "format":"int32"
        },
        "dueDate":{
            "type":"string",
            "description":"The date of installment collection/charge."
        },
        "amount":{
            "$ref":"#/components/schemas/Money"
        },
        "scheduleRef":{
            "type":"string",
            "description":"The reference to the installment schedule."
        },
        "customerRef":{
            "type":"string",
            "description":"The customer reference."
        }
    }
}

Response

201 Response

The installment schedule was created successfully, and the ID of the new schedule was returned.

500 Response

An error occurred. An exception has been raised.

Examples

This example shows how to create an installment schedule 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/installmentManagement/installmentScheduleSpec' -H 'content-type: application/json' -d @createInstallmentSchedule.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.
createInstallmentSchedule.json is the JSON file that specifies the installment schedule to create.

Example of Request Body

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

{   
    "name": "New Installment Schedule",   
    "descr": "descr",
    "billPreference": "IMMEDIATE",  
    "installmentType": "EQUAL_INSTALLMENT",
    "code": "newinstallment",
    "status": "OPEN",   
    "validFor": {   
        "startDateTime": "2021-07-28T21:28:02.763Z",    
        "endDateTime": "2021-08-28T21:28:02.763Z"   
    },   
    "totalInstallments": "2", 
    "totalAmount": {    
        "amount": "1000", 
        "currency": "INR"   
    },  
    "customerRef": "0.0.0.1+-account+134849+0",    
    "billProfileRef": "0.0.0.1+-billinfo+132545+0",    
    "bills": [  
        {   
            "billId": "0.0.0.1+-item+105318+7"
        }   
    ],  
    "scheduleSpecRef": "0.0.0.1+-config-installment-schedule_spec+82484", 
    "installments": [
        {   
            "status": "OPEN",   
            "dueDate": "2021-07-28T21:28:02.762Z",  
            "amount": { 
                "amount": "500",  
                "currency": "INR"
            }   
        },       
        {   
            "status": "OPEN",   
            "dueDate": "2021-08-28T21:28:02.763Z",  
            "amount": { 
                "amount": "500",  
                "currency": "INR"   
            }           
        }
    ]   
}

Example of Response Body

This example shows the contents of the response body in JSON format.

{
	"id": "0.0.0.1+installment_schedule+124524",
	"href": "http:// hostname:port/bcws/webresources/version/installmentManagement/installmentScheduleSpec/0.0.0.1+-installment_schedule+124524"
}