# Points Management API

## Create Points <a href="#id-07a52c88-6f10-4bb3-95bc-f1b0c43b8439" id="id-07a52c88-6f10-4bb3-95bc-f1b0c43b8439"></a>

**Endpoint**: `POST /api/points/create`

**Description**: Create a new point transaction for a user.

**Example Request**:

```json
curl -X POST "https://api.tbns.io/functions/v1/api/points/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU" \
  -H "X-Token: X-TOKEN" \
  -d '{
    "subid": "order-12345",
    "amount": 100,
    "user_view_text": "Points for completing survey",
    "user_id": "1749801330826x541366778024405570"
  }'
```

**Required Fields**:

* `subid`: External reference ID
* `amount`: Point amount (number)
* `user_view_text`: Description visible to user
* `user_id`: Target user's ID

**Default Status**: All new point transactions are created with status "Open"

## Get User Points/Transactions <a href="#id-70bb6786-a9e2-4b34-be96-4069a41a3862" id="id-70bb6786-a9e2-4b34-be96-4069a41a3862"></a>

**Endpoint**: `GET /api/user/points`

**Description**: Retrieve point transactions with optional filtering. Results are sorted by amount in descending order.

**6.1 Get All Transactions**

```
curl --location 'https://api.tbns.io/functions/v1/api/user/points' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU' \
--header 'X-Token: X-TOKEN'
```

**6.2 Filter by User ID**

```
curl --location 'https://api.tbns.io/functions/v1/api/user/points?user_id=1749801330826x541366778024405570' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU' \
--header 'X-Token: X-TOKEN'
```

**6.3 Filter by Status**

```
curl --location 'https://api.tbns.io/functions/v1/api/user/points&status=Closed' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU' \
--header 'X-Token: X-TOKEN'
```

**6.4 Combined Filters**

```
curl --location 'https://api.tbns.io/functions/v1/api/user/points?user_id=1749801330826x541366778024405570&status=Open' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU' \
--header 'X-Token: X-TOKEN'
```

**Query Parameters**:

* `user_id`: Filter by specific user ID
* `status`: Filter by transaction status (`Open`, `Closed`, `Pending`, `Approved`)

**Response**: Returns detailed transaction data including amounts, dates, and descriptions.

## Update Points Status <a href="#id-5df14bce-79e0-400a-bf27-b3f40a534142" id="id-5df14bce-79e0-400a-bf27-b3f40a534142"></a>

**Endpoint**: `PATCH /api/points/update`

**Description**: Update the status of a point transaction. Only transactions with "Open" status can be modified.

**Example Request**:

```
curl --location --request PATCH 'https://api.tbns.io/functions/v1/api/points/update' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imh3a2htcWF2enphaWVvdmtvdHdiIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDMwMDA3NDAsImV4cCI6MjA1ODU3Njc0MH0.nKjMLLZ7cY92nchtE2mFtBCOMqb0WWbiqkekaMqVFMU' \
--header 'X-Token: X-TOEKN' \
--header 'Content-Type: application/json' \
--data '{
    "point_id": "1749807859784x717369051962552600",
    "status": "Closed"
}'
```

**Required Fields**:

* `point_id`: ID of the point transaction to update
* `status`: New status (`Pending` or `Closed`)

**Business Rules**:

* Only transactions with status "Open" can be updated
* Transactions with status "Closed", "Approved", or "Pending" cannot be modified
* Returns descriptive error message if update is not allowed

**Allowed Status Values**:

* `Pending`: Transaction is pending approval ( Next payment cycle, this transaction will be charged to your payment method. )
* `Closed`: Transaction is closed/cancelled ( cancel points forever, visible for the user )

***

### Point Status Definitions <a href="#id-6cdce4a6-4562-4fca-a083-ec62a59719c6" id="id-6cdce4a6-4562-4fca-a083-ec62a59719c6"></a>

* **Open**: New transactions that can be modified ( by creating )
* **Pending**: Transactions approved from your site but not be paid ( you do it )
* **Closed**: Cancelled or closed transactions ( you do it )
* **Approved**: finalized transactions and ready to swap for the enduser ( we do it by payment )


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tbns.gitbook.io/tbns/references/points-management-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.