### Install Python SDK for Lava.top API

Source: https://developers.lava.top/en/index

This snippet shows how to install the official Python SDK for the Lava.top API using pip. Ensure you install its dependencies along with the SDK.

```bash
pip install lava-top-sdk
```

--------------------------------

### Install TypeScript SDK for Lava.top API

Source: https://developers.lava.top/en/index

This snippet demonstrates how to install the official TypeScript SDK for the Lava.top API using npm. This command adds the SDK as a dependency to your project.

```bash
npm install --save lava-top-sdk
```

--------------------------------

### Products API

Source: https://developers.lava.top/en/index

Manage digital products, including fetching product lists and updating parameters like price.

```APIDOC
## Products API

### Description
This section details the API endpoints for managing digital products. You can retrieve a list of available products and modify their attributes, such as pricing.

### Method
GET, PUT

### Endpoint
`/products`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of products to return.
- **offset** (integer) - Optional - The number of products to skip before starting to collect the result set.

#### Request Body (for PUT)
- **productId** (string) - Required - The unique identifier of the product.
- **price** (number) - Optional - The new price for the product.

### Request Example (GET)
```
GET /products?limit=10&offset=0
```

### Request Example (PUT)
```json
{
  "productId": "prod_123abc",
  "price": 29.99
}
```

### Response
#### Success Response (200)
- **products** (array) - A list of product objects, each containing details like `productId`, `name`, `price`.
- **total** (integer) - The total number of products available.

#### Response Example (GET)
```json
{
  "products": [
    {
      "productId": "prod_123abc",
      "name": "Example Product",
      "price": 19.99
    }
  ],
  "total": 100
}
```

#### Response Example (PUT)
```json
{
  "message": "Product updated successfully.",
  "productId": "prod_123abc",
  "newPrice": 29.99
}
```
```

--------------------------------

### Authentication and API Keys

Source: https://developers.lava.top/en/index

Information on how to authenticate API requests using API keys.

```APIDOC
## Authentication

### Description
Lava.top uses API keys for authenticating requests to its platform. You will need to obtain an API key from your account settings and include it in the `Authorization` header of your requests.

### Method
All HTTP Methods

### Endpoint
All Endpoints

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - The API key for authentication. Format: `ApiKey YOUR_API_KEY`

### Request Example
```
GET /products HTTP/1.1
Host: api.lava.top
Authorization: ApiKey YOUR_SECRET_API_KEY
```

### Obtaining API Keys
API keys can be generated in your Lava.top account under **Integrations → Public API → Create API Key**.
```

--------------------------------

### Webhook Management

Source: https://developers.lava.top/en/index

Manage your webhooks, including creating API keys and adding new webhooks. View sending attempt history, check webhook status, and resend failed webhooks.

```APIDOC
## Webhook Management

### Description
Configure API keys and webhooks in the **Integration** section. Monitor sending attempt history, check webhook status, and resend failed deliveries.

### Method
Not applicable (UI-driven actions)

### Endpoint
Not applicable (UI-driven actions)

### Parameters
Not applicable (UI-driven actions)

### Request Example
Not applicable (UI-driven actions)

### Response
Not applicable (UI-driven actions)
```

--------------------------------

### Add Kotlin SDK Dependency for Lava.top API

Source: https://developers.lava.top/en/index

This snippet provides the Maven dependency configuration to include the Lava.top Kotlin SDK in your project. Ensure you use the correct version.

```xml
<dependency>
	<groupId>top.lava</groupId>
	<artifactId>lava-top-kotlin-sdk</artifactId>
	<version>1.0.0</version>
</dependency>
```

--------------------------------

### Event Types

Source: https://developers.lava.top/en/index

Understand the different payment types and contract statuses that define event types for webhooks.

```APIDOC
## Event Types

### Description
Events are categorized by Payment Types and Contract Statuses. Understanding these helps in configuring the correct webhook types.

### Payment Types
- **one-time payment**: Initial purchase of a product, course, consultation, or the first payment in a subscription.
- **recurring payment**: Subsequent payments for a subscription renewal or cancellation.

### Contract Statuses
- **success**: Payment was successfully completed.
- **failed**: Payment was not completed (e.g., insufficient funds).
- **cancelled**: The subscription was cancelled.

### Event Types
- **payment.success**: Successful purchase of a product (not a donation) or the first subscription payment.
- **payment.failed**: Failed product purchase (not a donation) or failed first subscription payment.
- **subscription.recurring.payment.success**: Successful renewal of a subscription (second, third, and later payments).
- **subscription.recurring.payment.failed**: Failed subscription renewal.
- **subscription.cancelled**: Cancellation of a previously active subscription.

### Webhook Event Type Configuration
When creating a webhook, choose one of the following event types:
- **Payment result**: Receives `payment.success` and `payment.failed` events.
- **Recurring payment**: Receives `subscription.recurring.payment.success`, `subscription.recurring.payment.failed`, and `subscription.cancelled` events.
```

--------------------------------

### Invoices API

Source: https://developers.lava.top/en/index

Create purchase contracts and check the status of invoices.

```APIDOC
## Invoices API

### Description
This API allows you to generate new purchase contracts and query the status of existing invoices.

### Method
POST, GET

### Endpoint
`/invoices`

### Parameters
#### Query Parameters (for GET)
- **invoiceId** (string) - Required - The unique identifier of the invoice to retrieve.

#### Request Body (for POST)
- **items** (array) - Required - A list of items to include in the invoice. Each item should have `productId` and `quantity`.
- **customerId** (string) - Required - The ID of the customer for whom the invoice is being created.

### Request Example (POST)
```json
{
  "items": [
    {
      "productId": "prod_123abc",
      "quantity": 2
    }
  ],
  "customerId": "cust_xyz789"
}
```

### Request Example (GET)
```
GET /invoices?invoiceId=inv_456def
```

### Response
#### Success Response (200)
- **invoiceId** (string) - The unique identifier of the created or retrieved invoice.
- **status** (string) - The current status of the invoice (e.g., 'pending', 'paid', 'failed').
- **totalAmount** (number) - The total amount of the invoice.

#### Response Example (POST)
```json
{
  "invoiceId": "inv_456def",
  "status": "pending",
  "totalAmount": 39.98
}
```

#### Response Example (GET)
```json
{
  "invoiceId": "inv_456def",
  "status": "paid",
  "totalAmount": 39.98
}
```
```

--------------------------------

### Subscriptions API

Source: https://developers.lava.top/en/index

Manage user subscriptions, including creation, updates, and cancellations.

```APIDOC
## Subscriptions API

### Description
Manage user subscriptions via this API. Endpoints allow for creating new subscriptions, updating existing ones, and handling cancellations.

### Method
POST, PUT, DELETE, GET

### Endpoint
`/subscriptions`

### Parameters
#### Query Parameters (for GET)
- **userId** (string) - Required - The ID of the user whose subscriptions to retrieve.

#### Request Body (for POST)
- **userId** (string) - Required - The ID of the user subscribing.
- **planId** (string) - Required - The ID of the subscription plan.
- **paymentMethodId** (string) - Required - The ID of the payment method to use.

#### Request Body (for PUT)
- **subscriptionId** (string) - Required - The ID of the subscription to update.
- **newPlanId** (string) - Optional - The new subscription plan ID.

### Request Example (POST)
```json
{
  "userId": "user_abc123",
  "planId": "plan_premium",
  "paymentMethodId": "pm_456def"
}
```

### Request Example (PUT)
```json
{
  "subscriptionId": "sub_789ghi",
  "newPlanId": "plan_pro"
}
```

### Request Example (DELETE)
```
DELETE /subscriptions?subscriptionId=sub_789ghi
```

### Request Example (GET)
```
GET /subscriptions?userId=user_abc123
```

### Response
#### Success Response (200)
- **subscriptionId** (string) - The ID of the subscription.
- **status** (string) - The status of the subscription (e.g., 'active', 'canceled', 'past_due').
- **planId** (string) - The ID of the current subscription plan.

#### Response Example (POST/PUT/GET)
```json
{
  "subscriptionId": "sub_789ghi",
  "userId": "user_abc123",
  "planId": "plan_pro",
  "status": "active",
  "startDate": "2023-10-26T10:00:00Z",
  "endDate": "2024-10-26T10:00:00Z"
}
```

#### Response Example (DELETE)
```json
{
  "message": "Subscription canceled successfully."
}
```
```

--------------------------------

### Rate Limits

Source: https://developers.lava.top/en/index

Information on API request rate limiting policies.

```APIDOC
## Rate Limits

### Description
To ensure stable API performance and prevent overload, Lava.top implements request rate limiting. Exceeding these limits will result in a `429 Too Many Requests` error.

### Limits
- **Current limit**: Up to 50 requests per second per IP address.

### Handling Rate Limits
If you encounter a `429` error, it is recommended to wait for a short period before retrying your request. For services requiring higher load capacities, please contact support@lava.top.
```

--------------------------------

### Webhook Status

Source: https://developers.lava.top/en/index

Understand the possible statuses of a webhook delivery: DELIVERED or FAILED.

```APIDOC
## Webhook Status

### Description
The status indicates whether the webhook was successfully received by your server, determined by the HTTP response code.

### Statuses
- **DELIVERED**: The webhook was successfully delivered and processed.
- **FAILED**: The webhook delivery failed.
```

--------------------------------

### Webhook Management API

Source: https://developers.lava.top/en/index

Endpoints for managing webhooks, including retrieving webhook lists, retrying failed webhooks, and accessing webhook history with event details.

```APIDOC
## GET /webhooks

### Description
Retrieves a list of configured webhooks. Allows filtering and searching for webhooks based on various criteria.

### Method
GET

### Endpoint
/webhooks

### Query Parameters
- **productId** (string) - Optional - Filters webhooks by Product ID.
- **eventType** (string) - Optional - Filters webhooks by event type.
- **status** (string) - Optional - Filters webhooks by their status (e.g., SUCCESS, FAILED).

### Response
#### Success Response (200)
- **webhooks** (array) - A list of webhook objects.
  - **id** (string) - The unique identifier for the webhook.
  - **url** (string) - The URL where the webhook is sent.
  - **eventType** (string) - The type of event that triggered the webhook.
  - **status** (string) - The status of the webhook delivery.
  - **createdAt** (string) - The timestamp when the webhook was created.

#### Response Example
{
  "webhooks": [
    {
      "id": "wh_abc",
      "url": "https://example.com/webhook",
      "eventType": "PAYMENT_SUCCESS",
      "status": "SUCCESS",
      "createdAt": "2025-02-15T12:00:00Z"
    }
  ]
}

## POST /webhooks/{id}/retry

### Description
Manually retries sending a failed webhook.

### Method
POST

### Endpoint
/webhooks/{id}/retry

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook to retry.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the webhook retry has been initiated.

#### Response Example
{
  "message": "Webhook retry initiated successfully."
}
```

--------------------------------

### Donations API

Source: https://developers.lava.top/en/index

Generate donation links for processing payments.

```APIDOC
## Donations API

### Description
This API allows you to create secure donation links, facilitating easy payment processing for charitable contributions or other fundraising efforts.

### Method
POST

### Endpoint
`/donations/link`

### Parameters
#### Request Body
- **amount** (number) - Required - The donation amount.
- **currency** (string) - Required - The currency of the donation (e.g., 'USD', 'EUR').
- **description** (string) - Optional - A brief description for the donation.
- **callbackUrl** (string) - Optional - A URL to redirect the user to after a successful donation.

### Request Example
```json
{
  "amount": 50.00,
  "currency": "USD",
  "description": "Support our cause",
  "callbackUrl": "https://example.com/donation/success"
}
```

### Response
#### Success Response (200)
- **donationLink** (string) - The generated URL for the donation.
- **donationId** (string) - The unique identifier for this donation transaction.

#### Response Example
```json
{
  "donationLink": "https://lava.top/donate/xyz789abc",
  "donationId": "don_xyz789abc"
}
```
```

--------------------------------

### Invoice Management API (v2)

Source: https://developers.lava.top/en/index

Endpoints for managing invoices, including retrieving a list of invoices and fetching a specific invoice by its ID. Supports updated contract typing for different payment types.

```APIDOC
## GET /api/v2/invoices

### Description
Retrieves a list of invoices with updated contract typing. Supports various payment types including product payments, first subscription charges, and recurring subscription payments.

### Method
GET

### Endpoint
/api/v2/invoices

### Query Parameters
- **paymentType** (string) - Optional - Filters invoices by payment type (e.g., INVOICE, SUBSCRIPTION_FIRST_INVOICE, SUBSCRIPTION_RENEWAL).
- **startDate** (string) - Optional - Filters invoices by start date.
- **endDate** (string) - Optional - Filters invoices by end date.

### Response
#### Success Response (200)
- **invoices** (array) - A list of invoice objects.
  - **id** (string) - The unique identifier for the invoice.
  - **paymentType** (string) - The type of payment (e.g., INVOICE, SUBSCRIPTION_FIRST_INVOICE, SUBSCRIPTION_RENEWAL).
  - **amount** (number) - The amount of the invoice.
  - **currency** (string) - The currency of the invoice.
  - **status** (string) - The status of the invoice (e.g., PAID, PENDING, FAILED).
  - **createdAt** (string) - The timestamp when the invoice was created.
  - **parentInvoiceId** (string) - Optional - The ID of the parent transaction for subscriptions.

#### Response Example
{
  "invoices": [
    {
      "id": "inv_123",
      "paymentType": "INVOICE",
      "amount": 50.00,
      "currency": "USD",
      "status": "PAID",
      "createdAt": "2025-07-20T10:00:00Z",
      "parentInvoiceId": null
    },
    {
      "id": "inv_456",
      "paymentType": "SUBSCRIPTION_RENEWAL",
      "amount": 25.00,
      "currency": "USD",
      "status": "PAID",
      "createdAt": "2025-07-21T10:00:00Z",
      "parentInvoiceId": "sub_abc"
    }
  ]
}

## GET /api/v2/invoices/{id}

### Description
Retrieves a specific invoice by its ID, including updated contract typing for different payment types.

### Method
GET

### Endpoint
/api/v2/invoices/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the invoice to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the invoice.
- **paymentType** (string) - The type of payment (e.g., INVOICE, SUBSCRIPTION_FIRST_INVOICE, SUBSCRIPTION_RENEWAL).
- **amount** (number) - The amount of the invoice.
- **currency** (string) - The currency of the invoice.
- **status** (string) - The status of the invoice (e.g., PAID, PENDING, FAILED).
- **createdAt** (string) - The timestamp when the invoice was created.
- **parentInvoiceId** (string) - Optional - The ID of the parent transaction for subscriptions.

#### Response Example
{
  "id": "inv_123",
  "paymentType": "INVOICE",
  "amount": 50.00,
  "currency": "USD",
  "status": "PAID",
  "createdAt": "2025-07-20T10:00:00Z",
  "parentInvoiceId": null
}
```

--------------------------------

### Webhook Resend

Source: https://developers.lava.top/en/index

Manually resend a specific webhook if it failed or requires reprocessing.

```APIDOC
## Webhook Resend

### Description
Manually trigger a resend for any specific webhook that may have failed or needs to be reprocessed.

### Method
Not applicable (UI-driven action)

### Endpoint
Not applicable (UI-driven action)

### Action
Click the **arrow icon** next to the webhook entry and confirm the resend action.
```

--------------------------------

### Error Handling

Source: https://developers.lava.top/en/index

Details on standard HTTP response codes used for API errors and their meanings.

```APIDOC
## Error Handling

### Description
Lava.top utilizes standard HTTP status codes to communicate the success or failure of API requests. Below is a list of common error codes and their descriptions.

### Common Error Codes
- **400 Bad Request**: The request is invalid. Check syntax, parameters, size limits, etc.
- **401 Unauthorized**: Authentication error. Verify your API key, OAuth token, token expiration, or required scopes.
- **403 Forbidden**: Access to the resource is denied. You may lack permissions or be trying to access a restricted resource.
- **404 Not Found**: The resource was not found. Check the URL, object ID, or whether the resource exists in your account.
- **405 Method Not Allowed**: The HTTP method is not supported for this endpoint. Refer to the API documentation.
- **406 Not Acceptable**: Unsupported request or response format. The API only supports `application/json`.
- **408 Request Timeout**: The server timed out waiting for the request to complete. Try resending with smaller data payloads.
- **410 Gone**: The resource has been permanently deleted and is no longer available.
- **429 Too Many Requests**: Rate limit exceeded. Reduce the frequency of requests.
- **500 Internal Server Error**: A server-side error occurred. Try again later.
- **503 Service Unavailable**: The service is temporarily unavailable due to maintenance or overload. Please try again later.

### Retry Policy
If a webhook delivery fails, the system will attempt retries with increasing intervals: 1 second, 5 seconds, 15 seconds, followed by ten attempts every minute, and finally five attempts every hour. A total of up to 20 attempts will be made.
```

--------------------------------

### Retry Policy

Source: https://developers.lava.top/en/index

Details on Lava.top's retry mechanism for failed webhook deliveries, including the number of attempts and intervals.

```APIDOC
## Retry Policy

### Description
Lava.top employs a retry policy for failed webhook deliveries. If a webhook fails (non-successful HTTP status code), it will be retried up to 19 additional times, totaling 20 attempts.

### Retry Logic
- Initial attempts: 1s, 5s, 15s intervals.
- Subsequent attempts: 10 attempts with 1-minute intervals.
- Final attempts: 5 attempts with 1-hour intervals.

### Common Response Codes
- **401 / 403**: Invalid authentication data; access denied.
- **404**: Incorrect webhook URL.
- **500**: Server-side error on the webhook handler.
```

--------------------------------

### Webhook History

Source: https://developers.lava.top/en/index

Access and filter webhook history to view all events related to your configured webhooks. Examine payment details and delivery attempt history.

```APIDOC
## Webhook History

### Description
View the history of all events linked to your webhooks. Events are categorized by type, status, and API Key/webhook pair. Access detailed request bodies and delivery attempt history for each event. Use advanced filters like Buyer's email, Invoice ID, Product name, or Product ID.

### Method
Not applicable (UI-driven actions)

### Endpoint
**Integrations** → **Public API** → **Webhook History**

### Parameters
#### Query Parameters
- **buyer_email** (string) - Optional - Filter by buyer's email address.
- **invoice_id** (string) - Optional - Filter by invoice ID.
- **product_name** (string) - Optional - Filter by product name.
- **product_id** (string) - Optional - Filter by product ID.

### Request Example
Not applicable (UI-driven actions)

### Response
#### Success Response (200)
- **event_details** (object) - Contains details of a specific webhook event.
- **delivery_attempts** (array) - History of delivery attempts for the event.

#### Response Example
```json
{
  "event_details": {
    "buyer_email": "test@example.com",
    "invoice_id": "INV-12345",
    "product_name": "Sample Product",
    "event_type": "payment.success",
    "status": "DELIVERED",
    "timestamp": "2023-10-27T10:00:00Z"
  },
  "delivery_attempts": [
    {
      "timestamp": "2023-10-27T10:00:05Z",
      "status": "DELIVERED",
      "http_code": 200
    }
  ]
}
```
```

--------------------------------

### Reports API

Source: https://developers.lava.top/en/index

Access sales analytics data through the API.

```APIDOC
## Reports API

### Description
This API provides access to sales analytics data, allowing you to retrieve reports on various sales metrics.

### Method
GET

### Endpoint
`/reports/sales`

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the report (YYYY-MM-DD).
- **endDate** (string) - Required - The end date for the report (YYYY-MM-DD).
- **groupBy** (string) - Optional - The field to group the data by (e.g., 'day', 'product').

### Request Example
```
GET /reports/sales?startDate=2023-01-01&endDate=2023-01-31&groupBy=day
```

### Response
#### Success Response (200)
- **reportData** (array) - An array of objects, where each object represents a data point in the sales report, potentially grouped by the specified field.

#### Response Example
```json
{
  "reportData": [
    {
      "date": "2023-01-01",
      "totalSales": 1500.50,
      "numberOfOrders": 25
    },
    {
      "date": "2023-01-02",
      "totalSales": 1650.75,
      "numberOfOrders": 30
    }
  ]
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.