Update Promise To Pay

PATCH v2/finplus/debtmanagement/debtornotes/promisetopays/{id}

Use this endpoint to update a single promise-to-pay record for the specified school, without having to send the debtor note it belongs to.

The promise-to-pay ID must be included in the URL and can be found using the Get Promise To Pay(s) or Get Note(s) call.

Send only the fields you want to change. Any field you leave out keeps its current value.
At least one of date_promised, amount_promised or amount_paid must be supplied.
Unlike Update Note, which can also add new promise-to-pay entries, this endpoint only updates an existing one.

This endpoint is not enabled for every subscription. If your integration is not permitted to update promise-to-pay records the request will fail with a 401 Unauthorized. Contact d6 if you need it enabled.

Path Parameters

Name

Type

Description

{id}*

Integer

The promise-to-pay ID of the record to update

Request Headers

Name

Type

Description

HTTP-X-USERNAME*

String

As provided by d6

HTTP-X-PASSWORD*

String

As provided by d6

HTTP-X-SCHOOLID*

Integer

The unique identifier of the school for which the data is being queried.

Request Body

Name

Type

Description

date_promised

String

The date the payment is promised for, in "yyyy-mm-dd" format. Must fall between the start of the current year and the end of next year.

amount_promised

String

The amount promised. At most 2 decimal places, and at least 1.00.

amount_paid

String

The amount paid against the promise. At most 2 decimal places, and may not exceed amount_promised.

promise_completed is derived by d6 from the amounts and cannot be set directly. Sending it returns a 400 Bad Request.

How `promise_completed` is derived

The flag is recalculated on every update, using the values the record will hold once the update is applied, so it can never disagree with the amounts.

Condition

Resulting value

amount_paid is zero or not yet set

"No"

amount_paid is less than amount_promised

"Partial"

amount_paid equals or exceeds amount_promised

"Yes"

Request Examples

{
    "date_promised": "2025-08-31"
}

{
    "amount_paid": "750.00"
}

{
    "date_promised": "2025-08-31",
    "amount_promised": "1000.00",
    "amount_paid": "1000.00"
}

Response Examples

Status: 200 OK

{
    "success": true,
    "message": "Promise To Pay updated successfully",
    "data": {
        "promise_to_pay_id": 10,
        "accountable_person_id": 40,
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date_promised": "2024-04-30",
        "amount_promised": "1000.00",
        "amount_paid": "750.00",
        "promise_completed": "Partial"
    }
}

Description: When no promise-to-pay ID was provided

Status: 400 Bad Request

{
    "success": false,
    "message": "The Promise To Pay ID is required"
}

Description: When the request body contains none of the updatable fields

Status: 400 Bad Request

{
    "success": false,
    "message": "Nothing to update. Supply at least one of: date_promised, amount_promised, amount_paid"
}

Description: When amount_paid is greater than amount_promised. Increase amount_promised in the same request if the arrangement itself has changed.

Status: 400 Bad Request

{
    "success": false,
    "message": "The amount paid may not exceed the amount promised"
}

Description: When promise_completed is supplied. It is derived from the amounts.

Status: 400 Bad Request

{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "promise_completed": "This field is derived from amount_paid and cannot be set directly"
    }
}

Description: When validation failed for one or more fields

Status: 400 Bad Request

{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "date_promised": "The Date_promised is not valid date format. Expected format is 'Y-m-d'.",
        "amount_promised": "The amount_promised must be a positive amount with at most 2 decimal places"
    }
}

Description: When the promise-to-pay ID does not exist

Status: 404 Not Found

{
    "success": false,
    "message": "The Promise To Pay record does not exist"
}

Description: When your subscription is not permitted to update promise-to-pay records

Status: 401 Unauthorized

{
    "success": false,
    "message": "Request not authorised in subscription"
}

Code Samples

<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id    = 'the_school_id';

// The Promise To Pay record ID to be updated (required)
$id = '12345'; // Replace with the actual ID

// API Endpoint
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/promisetopays');

$url = BASE_URL . '/' . $id;

// Send only the fields you want to change
$request_data = [
    "date_promised"   => "2025-08-31",
    "amount_promised" => "1000.00",
    "amount_paid"     => "750.00"
];

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_POSTFIELDS     => json_encode($request_data),
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id",
        "Content-Type: application/json"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL and output response
curl_close($curl);
echo $response;

curl --location --request PATCH 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/promisetopays/12345' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "date_promised": "2025-08-31",
         "amount_promised": "1000.00",
         "amount_paid": "750.00"
     }'

PreviousGet Promise To Pay Record(s)

NextDelete Promise To Pay

Last updated 28 days ago

Path Parameters

Request Headers

Request Body

How promise_completed is derived

Request Examples

Response Examples

Code Samples

How `promise_completed` is derived