> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mageloyalty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adjust points

> Manually add or deduct points for a customer.

Manually add or deduct points for a customer. Useful for CS teams handling complaints, migrations from another platform, or any bespoke earning scenario not covered by earning rules.

## Request body

| Field                    | Type    | Required | Description                                                                                                                                                        |
| ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `adjustment`             | integer | Yes      | Points to add (positive) or deduct (negative). Cannot be zero.                                                                                                     |
| `note`                   | string  | No       | Internal note stored on the audit record                                                                                                                           |
| `update_lifetime_points` | boolean | No       | Whether to also adjust lifetime points. Default: `true`                                                                                                            |
| `send_email`             | boolean | No       | Whether to notify the customer of the adjustment. This gates both the points-earned email and the events sent to connected marketing integrations. Default: `true` |

```json theme={null}
{
  "adjustment": 500,
  "note": "Goodwill gesture after delayed order",
  "update_lifetime_points": true,
  "send_email": true
}
```

## Behaviour

* Points balance floors at `0` — deductions will never produce a negative balance
* Customer tier is recalculated automatically after the adjustment
* Creates an audit trail entry in the customer's earning history

## Response

Returns `200 OK` with a `points_adjustment` object.

## Errors

| Status | Scenario                                      |
| ------ | --------------------------------------------- |
| `400`  | `adjustment` missing, zero, or not an integer |
| `403`  | Customer is excluded from the loyalty program |
| `404`  | Customer not found                            |
| `500`  | The points adjustment could not be applied    |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.mageloyalty.com/v1/customers/6789012345/points \
    --header 'Authorization: <api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
    "adjustment": 500,
    "note": "Goodwill gesture after delayed order",
    "update_lifetime_points": true,
    "send_email": true
  }'
  ```

  ```javascript Node theme={null}
  const response = await fetch(
    "https://api.mageloyalty.com/v1/customers/6789012345/points",
    {
      method: "POST",
      headers: {
        Authorization: "<api-key>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        adjustment: 500,
        note: "Goodwill gesture after delayed order",
        update_lifetime_points: true,
        send_email: true,
      }),
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.mageloyalty.com/v1/customers/6789012345/points",
      headers={"Authorization": "<api-key>"},
      json={
          "adjustment": 500,
          "note": "Goodwill gesture after delayed order",
          "update_lifetime_points": True,
          "send_email": True,
      },
  )

  data = response.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.mageloyalty.com/v1/customers/6789012345/points");
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: <api-key>",
          "Content-Type: application/json",
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "adjustment" => 500,
          "note" => "Goodwill gesture after delayed order",
          "update_lifetime_points" => true,
          "send_email" => true,
      ]),
  ]);
  $data = json_decode(curl_exec($ch), true);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "type": "points_adjustment",
      "id": "6789012345",
      "attributes": {
        "shopify_customer_id": "6789012345",
        "adjustment": 500,
        "points_before": 200,
        "points_after": 700,
        "current_points": 700,
        "note": "Goodwill gesture after delayed order"
      }
    }
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "errors": [
      {
        "status": "403",
        "title": "Forbidden",
        "detail": "Customer is excluded from the loyalty program"
      }
    ]
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "errors": [
      {
        "status": "404",
        "title": "Not Found",
        "detail": "Customer '6789012345' not found"
      }
    ]
  }
  ```
</ResponseExample>