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

# Credit points

> Adds points to a customer's balance.

Use this to award points for something that happens outside Yuko, or to move balances over from another loyalty program. The points are added straight away and recorded in the customer's [activities](https://docs.yuko.so/developer/api/list-customer-activities.md) as a `point_adjustment` with your `description`. To award points for a repeatable action with a per-customer limit, use [Credit points for a custom action](https://docs.yuko.so/developer/api/credit-points-for-custom-action.md) instead.

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

## Body parameters

**identifier** `string` *required*

The customer to credit. 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).

**points** `integer` *required*

The number of points to add. Must be `1` or more.

**description** `string` *required*

The reason for the credit, up to 255 characters. It's shown in the customer's activity log.

**expires\_at** `integer`

When these points expire, as a Unix timestamp in seconds or milliseconds. Must be in the future. Leave it out for points that don't expire.

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

**points** `integer`

The number of points added.

**type** `string`

Always `credit`.

**expires\_at** `integer | null`

When the points expire, as a Unix timestamp in seconds. `null` if they don't expire.

## 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`. Message: "Customer not found". |
| `422` | `validation_error` | A body parameter is missing or invalid, for example `points` is below `1` or `expires_at` isn't in the future. |
| `422` | `adjustment_failed` | The customer is excluded from the loyalty program. Message: "Customer is banned". |
| `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/credit" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "identifier": "9049402769586",
    "points": 100,
    "description": "Points moved from our previous loyalty program",
    "expires_at": 1798761600
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.yukoapp.com/api/v1/public/customers/points/credit",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      identifier: "9049402769586",
      points: 100,
      description: "Points moved from our previous loyalty program",
      expires_at: 1798761600,
    }),
  }
);

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

```php PHP theme={null}
$payload = json_encode([
    "identifier" => "9049402769586",
    "points" => 100,
    "description" => "Points moved from our previous loyalty program",
    "expires_at" => 1798761600,
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers/points/credit");
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": "d4e5f6a7-b8c9-4123-8efa-b01234567890",
    "customer_id": "9049402769586",
    "points": 100,
    "type": "credit",
    "expires_at": 1798761600
  }
}
```

```json 422 (validation) theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The description field is required.",
    "details": {
      "description": ["The description field is required."]
    }
  }
}
```

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


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