> For the complete documentation index, see [llms.txt](https://tbns.gitbook.io/tbns/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tbns.gitbook.io/tbns/references/points-management-api.md).

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