> 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**

#### Overview

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