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

# Create a points transaction

Add or remove points from a customer's balance. Pass a positive `points` value to credit points, or a negative value to debit them.

Debit transactions that would result in a negative points balance will be rejected.

**POST /public/customers/transactions**

#### **Authorizations**

**Authorization**

**string**

**header**

**required**

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your REST API token.

#### **Required Scope**

**`transactions:write`**

This endpoint requires the `transactions` scope with **Read/Write Access**. Configure token scopes in Settings → Integrations → REST API.

#### **Query Parameters**

**customer\_id**

**string**

**required**

The platform customer ID (e.g. Shopify customer ID)

Example:

`"9049402769586"`

#### **Body**

**application/json**

**points**

**integer**

**required**

The number of points to add or remove. Use a positive value to credit points and a negative value to debit. Cannot be zero.

Example:

`100`

**description**

**string**

**required**

A human-readable reason for the adjustment, visible in the customer's activity log.

Example:

`"Bonus points for completing a survey"`

#### **Response**

**201 - application/json**

The points transaction was successfully created.

**data**

**object**

Hide child attributes

**data.transaction\_id**

**string\<uuid>**

The UUID of the newly created transaction.

Example:

`"d4e5f6a7-b8c9-0123-defa-b01234567890"`

**data.customer\_id**

**string\<uuid>**

The UUID of the customer whose balance was adjusted.

Example:

`"63a2c89a-9936-4bc0-9d5f-93db46110b76"`

**data.points**

**integer**

The points value as submitted (positive for credit, negative for debit).

Example:

`100`

**data.type**

**enum\<string>**

Whether the transaction was a credit or debit.

Available options:

`credit`,

`debit`

Example:

`"credit"`

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.yukoapp.com/api/v1/public/customers/transactions" \
    --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    --header "Content-Type: application/json" \
    --data '{
      "points": 100,
      "description": "Bonus points for completing a survey"
    }'
  ```

  ```javascript JavaScript theme={null}
  const customerId = "9049402769586";

  const response = await fetch(
    `https://api.yukoapp.com/api/v1/public/customers/transactions`,
    {
      method: "POST",
      headers: {
        Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        points: 100,
        description: "Bonus points for completing a survey",
      }),
    }
  );

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

  ```php PHP theme={null}
  $customerId = "9049402769586";
  $payload = json_encode([
      "points" => 100,
      "description" => "Bonus points for completing a survey",
  ]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers/transactions");
  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",
      "Content-Type: application/json",
  ]);

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

  $data = json_decode($response, true);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "transaction_id": "d4e5f6a7-b8c9-0123-defa-b01234567890",
      "customer_id": "63a2c89a-9936-4bc0-9d5f-93db46110b76",
      "points": 100,
      "type": "credit"
    }
  }
  ```

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

  ```json 422 theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "The given data was invalid",
      "details": {
        "points": ["The points field is required."],
        "description": ["The description field is required."]
      }
    }
  }
  ```

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

  ```json 401 theme={null}
  {
    "error": {
      "code": "invalid_token",
      "message": "Invalid or revoked API token"
    }
  }
  ```
</ResponseExample>