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

# Introduction

### **Tip4Serv API Introduction**

The **Tip4Serv API** is organized around **REST principles**.\
It provides predictable, resource-oriented endpoints, supports **JSON-encoded requests and responses**, and uses standard **HTTP verbs**, **status codes**, and **authentication methods**.

This API allows you to programmatically manage your Tip4Serv store, customers, products, subscriptions, and many more.\
You can automate operations that you normally perform in your Tip4Serv dashboard, such as unsubscribing, retrieving customer data, or applying discounts.

The base URL for all API requests is:

```
https://api.tip4serv.com/v1
```

***

#### Authentication

All requests to the Tip4Serv API must be authenticated using a **Bearer Token**.

You can find or regenerate your API key in your **Tip4Serv Dashboard** under **Store → API Keys**.

[Generate your API Key here.](https://tip4serv.com/dashboard/api-keys)\
Include your API key in the `Authorization` header of each request:

```bash
curl https://api.tip4serv.com/v1/customers \
  -H "Authorization: Bearer sk_live_your_secret_key"
```

**Notes:**

* All API requests must be made over **HTTPS**.
* Calls made over plain HTTP will fail.
* Requests without proper authentication will return a **403 Forbidden** response.

Keep your API keys secure and **never share them publicly** (e.g., on GitHub or client-side code).

***

#### API Structure

The API exposes several resource groups, each corresponding to a logical part of your store:

| Resource          | Description                                        |
| ----------------- | -------------------------------------------------- |
| **Customers**     | Manage customer profiles and related data          |
| **Subscriptions** | Create, renew, and cancel recurring subscriptions  |
| **Store**         | Retrieve store-level information and configuration |
| **Servers**       | Manage connected game servers                      |
| **Products**      | Retrieve, create, and update store products        |
| **Discounts**     | Apply and manage promotional discounts             |

Each group is represented by a **tag** in the OpenAPI documentation.

***

#### Example Request

Here’s a simple example to retrieve your store’s list of products:

```bash
GET https://api.tip4serv.com/v1/store/products
```

**Response Example:**

```json
{
  "products": [
    {
      "id": 123,
      "name": "VIP Access",
      "price": 9.99,
      "currency": "EUR",
      "enabled": true
    }
  ],
  "product_count": 120
}
```

You can use standard query parameters for pagination and filtering.\
For example:

```
GET /store/products?page=2
```

***

#### Error Handling

The API uses standard HTTP status codes to indicate request success or failure.

| Code                      | Meaning                                                |
| ------------------------- | ------------------------------------------------------ |
| **200 OK**                | Request succeeded                                      |
| **400 Bad Request**       | One of the parameter is missing is in the wrong format |
| **403 Forbidden**         | API key is missing or lacks permission                 |
| **404 Not Found**         | Requested resource does not exist                      |
| **409 Conflict**          | Conflicting operation (e.g., maximum server reached)   |
| **429 Too Many Requests** | Rate limit exceeded                                    |
| **500–503 Server Errors** | Internal Tip4Serv server error                         |

**Example Error Response:**

```json
{
  "error": {
    "status": 400,
    "message": "One of the parameter is missing is in the wrong format."
  }
}
```

***

#### Rate Limiting

To ensure stability, the API enforces rate limits.\
If you exceed these limits, you’ll receive a `429 Too Many Requests` response.\
Implement a **caching mechanism** to avoid being rate limitted.

***

#### Versioning

The current API version is **1.0.12**.\
Backward-compatible updates may be released periodically.\
Major changes will trigger a new version identifier.

***

#### Support

For technical questions, reach out to us on [Discord](https://tip4serv.com/discord) or contact us via e-mail at **<contact@tip4serv.com>**.