> ## 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 for a custom action

> Awards a customer the points set on a Custom Action earn rule.

A **Custom Action** is a way to earn that you define in Yuko, such as *Complete a survey* or *Attend an event*. You set the points, an optional limit on how often each customer can earn them, and an optional expiry. Call this endpoint each time a customer completes the action, and Yuko awards the points by the rule's settings.

To set one up, go to **Shopify admin → Apps → Yuko Loyalty → Loyalty → Programs → Ways to earn → Add another way → Custom Action**. After you save it, the **REST API** card on the rule shows the full URL to call, including its `campaign` ID.

> [!NOTE]
>
> Requires the `write:transactions` scope. Custom actions are available on paid plans. See [Scopes](https://docs.yuko.so/developer/api/scopes.md).

## Path parameters

**campaign** `string\<uuid\>` *required*

The ID of the Custom Action earn rule. Copy it from the **REST API** card on the rule, or use the rule's `id` from [List ways to earn](https://docs.yuko.so/developer/api/list-ways-to-earn.md).

## Body parameters

**identifier** `string` *required*

The customer who completed the action. 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).

## Response

Returns `201 Created`.

**data** `object`

**data properties**

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

The Custom Action earn rule that was credited.

**customer\_id** `string`

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

**points** `integer`

The number of points awarded, including the customer's VIP tier multiplier if the rule uses tier multipliers.

**status** `string | null`

The status of the points: `active` when they can be spent now, or `on_hold` when they're held before being released.

## 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`. |
| `403` | `plan_upgrade_required` | The store's plan doesn't include custom actions. Message: "Custom actions are available on paid plans." |
| `404` | `not_found` | `campaign` isn't a Custom Action earn rule in this store ("Custom action not found"), or no customer matches `identifier` ("Customer not found"). |
| `422` | `validation_error` | `identifier` is missing. |
| `422` | `action_inactive` | The earn rule is turned off. Message: "This custom action is not active." |
| `422` | `limit_reached` | The customer has already earned the maximum number of times in the rule's limit period. Message: "This customer has reached the earning limit for this action." |
| `422` | `credit_failed` | No points could be awarded, for example because the customer is excluded from the loyalty program. |
| `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/5c1d2e3f-4a5b-4c6d-8e7f-901234567890" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "identifier": "9049402769586"
  }'
```

```javascript JavaScript theme={null}
const campaignId = "5c1d2e3f-4a5b-4c6d-8e7f-901234567890";

const response = await fetch(
  `https://api.yukoapp.com/api/v1/public/customers/points/credit/${campaignId}`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ identifier: "9049402769586" }),
  }
);

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

```php PHP theme={null}
$campaignId = "5c1d2e3f-4a5b-4c6d-8e7f-901234567890";
$payload = json_encode(["identifier" => "9049402769586"]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers/points/credit/{$campaignId}");
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": {
    "campaign_id": "5c1d2e3f-4a5b-4c6d-8e7f-901234567890",
    "customer_id": "9049402769586",
    "points": 50,
    "status": "active"
  }
}
```

```json 422 (limit reached) theme={null}
{
  "error": {
    "code": "limit_reached",
    "message": "This customer has reached the earning limit for this action."
  }
}
```

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


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