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

# Debit points

> Deducts a reward's points cost from a customer's balance.

Use this when your own system gives the customer a reward from your Yuko catalogue, for example in a custom checkout or app. Yuko deducts the reward's points cost and records the redemption in the customer's [activities](https://docs.yuko.so/developer/api/list-customer-activities.md) as "Redeemed reward: *reward name*".

> [!WARNING]
>
> Yuko only deducts the points. It doesn't create a discount code or store credit, so your system is responsible for giving the customer the reward.

The reward must be an active online reward from [List rewards](https://docs.yuko.so/developer/api/list-rewards.md). Shopify POS rewards can't be used. Points are taken from the customer's oldest points first.

> [!NOTE]
>
> Requires the `write:transactions` scope. See [Scopes](https://docs.yuko.so/developer/api/scopes.md).

## Body parameters

**identifier** `string` *required*

The customer to debit. Accepts the Shopify customer ID, Yuko's customer `id` (a UUID), the customer's email address or their phone number. See [Identifying customers](https://docs.yuko.so/create-or-update-a-customer-identity.md#identifying-customers).

**reward\_id** `string\<uuid\>` *required*

The `id` of the reward from [List rewards](https://docs.yuko.so/developer/api/list-rewards.md). The reward's `points_cost` is deducted.

## Response

Returns `201 Created`.

**data** `object`

**data properties**

**transaction\_id** `string\<uuid\>`

The ID of the new points transaction.

**customer\_id** `string`

The customer's Shopify customer ID (`platform_customer_id`).

**reward\_id** `string\<uuid\>`

The reward that was redeemed.

**points** `integer`

The number of points deducted (the reward's points cost).

**type** `string`

Always `debit`.

## Errors

| Status | Code | When |
| :- | :- | :- |
| `401` | `missing_token`, `invalid_token` | The API key is missing, wrong or revoked. |
| `403` | `insufficient_scope` | The key doesn't have `write:transactions`. |
| `404` | `not_found` | No customer matches `identifier` ("Customer not found"), or `reward_id` isn't an active online reward ("Reward not found"). |
| `422` | `validation_error` | `identifier` or `reward_id` is missing, or `reward_id` isn't a UUID. |
| `422` | `adjustment_failed` | The points couldn't be deducted. Messages: "Insufficient point balance", "Customer is banned", "This reward has no points cost.", or "Another points update is in progress. Please try again." |
| `429` | | You exceeded the [rate limit](https://docs.yuko.so/developer/api/rate-limits.md). |

```bash cURL theme={null}
curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/customers/points/debit" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "identifier": "jane.smith@example.com",
    "reward_id": "b2c3d4e5-f6a7-4901-8cde-f12345678901"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.yukoapp.com/api/v1/public/customers/points/debit",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      identifier: "jane.smith@example.com",
      reward_id: "b2c3d4e5-f6a7-4901-8cde-f12345678901",
    }),
  }
);

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

```php PHP theme={null}
$payload = json_encode([
    "identifier" => "jane.smith@example.com",
    "reward_id" => "b2c3d4e5-f6a7-4901-8cde-f12345678901",
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers/points/debit");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Accept: application/json",
    "Content-Type: application/json",
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
```

```json 201 theme={null}
{
  "data": {
    "transaction_id": "e5f6a7b8-c9d0-4234-8fab-c12345678901",
    "customer_id": "9049402769586",
    "reward_id": "b2c3d4e5-f6a7-4901-8cde-f12345678901",
    "points": 500,
    "type": "debit"
  }
}
```

```json 422 (insufficient balance) theme={null}
{
  "error": {
    "code": "adjustment_failed",
    "message": "Insufficient point balance"
  }
}
```

```json 404 theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Reward not found"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.