> For the complete documentation index, see [llms.txt](https://apidocs.d6plus.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.d6plus.co.za/v2/reference/finance+/debt-management/debtor-notes/update-promise-to-pay.md).

# Update Promise To Pay

<mark style="color:purple;">`PATCH`</mark> `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)](/v2/reference/finance+/debt-management/debtor-notes/get-promise-to-pay-record-s.md) or [Get Note(s)](/v2/reference/finance+/debt-management/debtor-notes/get-note-s.md) 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](/v2/reference/finance+/debt-management/debtor-notes/update-note.md), which can also add new promise-to-pay entries, this endpoint only updates an existing one.

{% hint style="info" %}
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.
{% endhint %}

### Path Parameters

<table><thead><tr><th width="210.2857666015625">Name</th><th width="145.05712890625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>{id}</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The <strong>promise-to-pay ID</strong> of the record to update</td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="212.257080078125">Name</th><th width="114.28582763671875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>HTTP-X-USERNAME</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-PASSWORD</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-SCHOOLID</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The unique identifier of the school for which the data is being queried.</td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="219.85711669921875">Name</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>date_promised</code></td><td>String</td><td>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.</td></tr><tr><td><code>amount_promised</code></td><td>String</td><td>The amount promised. At most 2 decimal places, and at least 1.00.</td></tr><tr><td><code>amount_paid</code></td><td>String</td><td>The amount paid against the promise. At most 2 decimal places, and may not exceed <code>amount_promised</code>.</td></tr></tbody></table>

{% hint style="warning" %}
`promise_completed` is derived by d6 from the amounts and cannot be set directly. Sending it returns a `400 Bad Request`.
{% endhint %}

### 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.

<table><thead><tr><th width="300">Condition</th><th>Resulting value</th></tr></thead><tbody><tr><td><code>amount_paid</code> is zero or not yet set</td><td><code>"No"</code></td></tr><tr><td><code>amount_paid</code> is less than <code>amount_promised</code></td><td><code>"Partial"</code></td></tr><tr><td><code>amount_paid</code> equals or exceeds <code>amount_promised</code></td><td><code>"Yes"</code></td></tr></tbody></table>

### Request Examples

{% tabs %}
{% tab title="Reschedule a promise" %}

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

{% endtab %}

{% tab title="Record a part payment" %}

```json
{
    "amount_paid": "750.00"
}
```

{% endtab %}

{% tab title="Update the full arrangement" %}

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

{% endtab %}
{% endtabs %}

### Response Examples

{% tabs %}
{% tab title="Success (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "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"
    }
}
```

{% endtab %}

{% tab title="ID Missing Error (400 Bad Request)" %}
**Description:** When no promise-to-pay ID was provided

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

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

{% endtab %}

{% tab title="Nothing To Update Error (400 Bad Request)" %}
**Description:** When the request body contains none of the updatable fields

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

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

{% endtab %}

{% tab title="Overpayment Error (400 Bad Request)" %}
**Description:** When `amount_paid` is greater than `amount_promised`. Increase `amount_promised` in the same request if the arrangement itself has changed.

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

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

{% endtab %}

{% tab title="Derived Field Error (400 Bad Request)" %}
**Description:** When `promise_completed` is supplied. It is derived from the amounts.

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

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

{% endtab %}

{% tab title="Validation Error (400 Bad Request)" %}
**Description:** When validation failed for one or more fields

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "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"
    }
}
```

{% endtab %}

{% tab title="ID Not Found Error (404 Not Found)" %}
**Description:** When the promise-to-pay ID does not exist

**Status:** <mark style="color:red;">`404 Not Found`</mark>

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

{% endtab %}

{% tab title="Not Permitted (401 Unauthorized)" %}
**Description:** When your subscription is not permitted to update promise-to-pay records

**Status:** <mark style="color:red;">`401 Unauthorized`</mark>

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

{% endtab %}
{% endtabs %}

### Code Samples

{% tabs %}
{% tab title="PHP" %}

```php
<?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;

```

{% endtab %}

{% tab title="cURL" %}

```bash
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"
     }'
```

{% endtab %}
{% endtabs %}