### Setup Stripe Payment Gateway - Unibee API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Configures the Stripe payment gateway integration. This requires providing API credentials, minimum transaction amounts, supported currencies, and country-specific configurations. The response confirms the gateway setup and lists the enabled currencies.

```bash
curl -X POST https://api.unibee.dev/merchant/gateway/setup \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "gatewayName": "stripe",
    "gatewayKey": {
      "apiKey": "sk_test_51Ab...",
      "publishableKey": "pk_test_51Ab...",
      "webhookSecret": "whsec_..."
    },
    "minimumAmount": 50,
    "currency": ["USD", "EUR", "GBP"],
    "countryConfig": [
      {
        "countryCode": "US",
        "currency": "USD"
      }
    ]
  }'
```

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

### GET /merchant/webhook/event_list

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Retrieves a list of all available webhook event types that can be subscribed to.

```APIDOC
## GET /merchant/webhook/event_list

### Description
Retrieves a list of all available webhook event types that Unibee can emit. This helps in configuring which events your webhook endpoints should subscribe to.

### Method
GET

### Endpoint
/merchant/webhook/event_list

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **data** (object)
  - **eventList** (array of strings) - A list of all available event types.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "eventList": [
      "invoice.created",
      "invoice.paid",
      "invoice.failed",
      "invoice.cancelled",
      "subscription.created",
      "subscription.updated",
      "subscription.cancelled",
      "payment.success",
      "payment.failed"
    ]
  }
}
```
```

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

### Create Subscription

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Initiates a new subscription for a user, specifying the plan, addons, discounts, and payment gateway. This POST request requires authentication and a JSON body with subscription details.

```bash
curl -X POST https://api.unibee.dev/merchant/subscription/create_submit \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 5001,
    "planId": 2001,
    "quantity": 1,
    "gatewayId": 1,
    "addonParams": [
      {
        "addonPlanId": 2050,
        "quantity": 2
      }
    ],
    "discountCode": "LAUNCH2024",
    "trialEnd": 1704067200,
    "startIncomplete": false,
    "returnUrl": "https://myapp.com/subscription/success",
    "cancelUrl": "https://myapp.com/subscription/cancel",
    "metadata": {
      "source": "web_checkout",
      "campaign": "spring_promo"
    },
    "vatNumber": "GB123456789",
    "taxPercentage": 2000
  }'
```

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

### GET /merchant/webhook/endpoint_list

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Retrieves a list of all registered webhook endpoints.

```APIDOC
## GET /merchant/webhook/endpoint_list

### Description
Retrieves a list of all registered webhook endpoints for your merchant account. This allows you to view your current webhook configurations.

### Method
GET

### Endpoint
/merchant/webhook/endpoint_list

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **data** (object)
  - **endpointList** (array of objects)
    - **id** (integer) - The ID of the webhook endpoint.
    - **url** (string) - The URL of the webhook endpoint.
    - **events** (array of strings) - The list of events subscribed to by this endpoint.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "endpointList": [
      {
        "id": 2001,
        "url": "https://myapp.com/webhooks/unibee",
        "events": ["invoice.created", "invoice.paid", "subscription.created"]
      }
    ]
  }
}
```
```

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

### Preview Subscription Creation

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Calculates prorated charges, taxes, and the total amount for a potential subscription before it is created. This POST request requires authentication and a JSON body with user and plan details.

```bash
curl -X POST https://api.unibee.dev/merchant/subscription/create_preview \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 5001,
    "planId": 2001,
    "quantity": 1,
    "gatewayId": 1,
    "addonParams": [
      {
        "addonPlanId": 2050,
        "quantity": 2
      }
    ],
    "discountCode": "LAUNCH2024",
    "vatNumber": "GB123456789"
  }'
```

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

### GET /merchant/webhook/endpoint_log_list

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Retrieves logs for webhook deliveries to a specific endpoint.

```APIDOC
## GET /merchant/webhook/endpoint_log_list

### Description
Retrieves logs for webhook deliveries to a specific endpoint. This is useful for monitoring the status of events sent to your webhook and troubleshooting delivery issues.

### Method
GET

### Endpoint
/merchant/webhook/endpoint_log_list

### Parameters
#### Query Parameters
- **endpointId** (integer) - Required - The ID of the webhook endpoint to retrieve logs for.
- **page** (integer) - Optional - The page number for pagination (defaults to 0).
- **count** (integer) - Optional - The number of logs to retrieve per page (defaults to 20).

### Request Example
```
GET https://api.unibee.dev/merchant/webhook/endpoint_log_list?endpointId=2001&page=0&count=20
```

### Response
(Note: The exact structure of the response for logs is not provided in the input, but a typical response would include details like event ID, delivery status, timestamp, and any error messages.)

#### Success Response (200)
- **code** (integer) - 0 for success.
- **data** (object) - Contains the webhook delivery logs.
  - **logs** (array of objects) - Details of each webhook delivery attempt.
```

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

### POST /merchant/subscription/create_preview

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Calculate prorated charges, taxes, and total amount before creating a subscription. This endpoint provides a preview of subscription costs.

```APIDOC
## POST /merchant/subscription/create_preview

### Description
Calculate prorated charges, taxes, and total amount before creating subscription.

### Method
POST

### Endpoint
/merchant/subscription/create_preview

### Parameters
#### Request Body
- **userId** (integer) - Required - ID of the user.
- **planId** (integer) - Required - ID of the plan.
- **quantity** (integer) - Optional - Quantity of the plan (default: 1).
- **gatewayId** (integer) - Required - ID of the payment gateway.
- **addonParams** (array) - Optional - Addon subscriptions.
  - **addonPlanId** (integer) - Required - ID of the addon plan.
  - **quantity** (integer) - Required - Quantity of the addon.
- **discountCode** (string) - Optional - Discount code to apply.
- **vatNumber** (string) - Optional - VAT number for tax purposes.

### Request Example
```json
{
  "userId": 5001,
  "planId": 2001,
  "quantity": 1,
  "gatewayId": 1,
  "addonParams": [
    {
      "addonPlanId": 2050,
      "quantity": 2
    }
  ],
  "discountCode": "LAUNCH2024",
  "vatNumber": "GB123456789"
}
```

### Response
#### Success Response (200)
- **code** (integer) - Response code.
- **data** (object)
  - **currency** (string) - Currency code.
  - **totalAmount** (integer) - Total amount in cents.
  - **taxAmount** (integer) - Tax amount in cents.
  - **discountAmount** (integer) - Discount amount in cents.
  - **originAmount** (integer) - Original amount before discounts and taxes (in cents).
  - **invoice** (object)
    - **lines** (array) - Line items of the invoice.
      - **name** (string) - Name of the line item.
      - **amount** (integer) - Amount in cents.
      - **quantity** (integer) - Quantity.
      - **amountExcludingTax** (integer) - Amount excluding tax (in cents).
      - **tax** (integer) - Tax amount for the line item (in cents).
    - **discount** (object)
      - **code** (string) - Discount code applied.
      - **amount** (integer) - Discount amount in cents.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "currency": "USD",
    "totalAmount": 6860,
    "taxAmount": 1372,
    "discountAmount": 490,
    "originAmount": 7900,
    "invoice": {
      "lines": [
        {
          "name": "Professional Monthly",
          "amount": 4900,
          "quantity": 1,
          "amountExcludingTax": 4083,
          "tax": 817
        },
        {
          "name": "Extra Storage Addon",
          "amount": 2000,
          "quantity": 2,
          "amountExcludingTax": 1667,
          "tax": 333
        }
      ],
      "discount": {
        "code": "LAUNCH2024",
        "amount": 490
      }
    }
  }
}
```
```

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

### Create Payment - Unibee API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Handles the creation of one-time payments. Supports multiple line items, tax calculations, and selection of payment gateways. Includes options for redirect and cancel URLs.

```bash
curl -X POST https://api.unibee.dev/merchant/payment/new \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "externalPaymentId": "order-2024-001",
    "userId": 5001,
    "currency": "USD",
    "totalAmount": 15000,
    "gatewayId": 1,
    "redirectUrl": "https://myapp.com/payment/success",
    "cancelUrl": "https://myapp.com/payment/cancel",
    "name": "Product Purchase",
    "description": "3 items",
    "items": [
      {
        "amount": 10000,
        "name": "Premium Widget",
        "description": "Color: Blue, Size: Large",
        "quantity": 2,
        "currency": "USD",
        "unitAmountExcludingTax": 4167,
        "amountExcludingTax": 8334,
        "tax": 1666,
        "taxPercentage": 2000
      },
      {
        "amount": 5000,
        "name": "Shipping",
        "quantity": 1,
        "currency": "USD",
        "unitAmountExcludingTax": 5000,
        "amountExcludingTax": 5000,
        "tax": 0,
        "taxPercentage": 0
      }
    ],
    "metadata": {
      "orderId": "order-2024-001",
      "source": "web",
      "customerIp": "192.168.1.1"
    },
    "sendInvoice": true
  }'
```

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

### Get User Credit Detail - Unibee API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Retrieves the credit account details for a specific user. This is used to check a user's available credit balance, which can be applied to their account for prepaid billing or promotional purposes. The query requires the user's ID.

```bash
curl -X GET "https://api.unibee.dev/merchant/credit/detail?userId=5001" \
  -H "Authorization: Bearer {token}"
```

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

### POST /merchant/subscription/create_submit

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Initiate new subscription for a user with specified plan, addons, discounts, and payment gateway. This endpoint creates and processes a new subscription.

```APIDOC
## POST /merchant/subscription/create_submit

### Description
Initiate new subscription for user with plan, addons, discounts, and payment gateway.

### Method
POST

### Endpoint
/merchant/subscription/create_submit

### Parameters
#### Request Body
- **userId** (integer) - Required - ID of the user subscribing.
- **planId** (integer) - Required - ID of the plan to subscribe to.
- **quantity** (integer) - Optional - Quantity of the plan (default: 1).
- **gatewayId** (integer) - Required - ID of the payment gateway.
- **addonParams** (array) - Optional - Addon subscriptions.
  - **addonPlanId** (integer) - Required - ID of the addon plan.
  - **quantity** (integer) - Required - Quantity of the addon.
- **discountCode** (string) - Optional - Discount code to apply.
- **trialEnd** (integer) - Optional - Unix timestamp for trial end.
- **startIncomplete** (boolean) - Optional - Whether to start subscription in incomplete state.
- **returnUrl** (string) - Optional - URL to redirect after successful subscription.
- **cancelUrl** (string) - Optional - URL to redirect if subscription is cancelled.
- **metadata** (object) - Optional - Key-value pairs for custom data.
- **vatNumber** (string) - Optional - VAT number for tax purposes.
- **taxPercentage** (integer) - Optional - Tax percentage to apply.

### Request Example
```json
{
  "userId": 5001,
  "planId": 2001,
  "quantity": 1,
  "gatewayId": 1,
  "addonParams": [
    {
      "addonPlanId": 2050,
      "quantity": 2
    }
  ],
  "discountCode": "LAUNCH2024",
  "trialEnd": 1704067200,
  "startIncomplete": false,
  "returnUrl": "https://myapp.com/subscription/success",
  "cancelUrl": "https://myapp.com/subscription/cancel",
  "metadata": {
    "source": "web_checkout",
    "campaign": "spring_promo"
  },
  "vatNumber": "GB123456789",
  "taxPercentage": 2000
}
```

### Response
#### Success Response (200)
- **code** (integer) - Response code.
- **data** (object)
  - **subscription** (object)
    - **subscriptionId** (string) - Unique ID of the subscription.
    - **userId** (integer) - ID of the user.
    - **planId** (integer) - ID of the plan.
    - **status** (integer) - Subscription status.
    - **currentPeriodStart** (integer) - Unix timestamp for current period start.
    - **currentPeriodEnd** (integer) - Unix timestamp for current period end.
    - **trialEnd** (integer) - Unix timestamp for trial end.
    - **amount** (integer) - Subscription amount in cents.
    - **currency** (string) - Currency code.
  - **paid** (boolean) - Whether the subscription is paid.
  - **link** (string) - URL for payment or checkout.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "subscription": {
      "subscriptionId": "sub_1234567890",
      "userId": 5001,
      "planId": 2001,
      "status": 2,
      "currentPeriodStart": 1704067200,
      "currentPeriodEnd": 1706745600,
      "trialEnd": 1704067200,
      "amount": 4900,
      "currency": "USD"
    },
    "paid": true,
    "link": "https://checkout.stripe.com/c/pay/cs_test_..."
  }
}
```
```

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

### Create Subscription Plan

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Defines a recurring billing plan with specified pricing, intervals, trial periods, and metric limits. This endpoint requires authentication and sends a JSON payload with plan details.

```bash
curl -X POST https://api.unibee.dev/merchant/plan/new \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "externalPlanId": "pro-monthly-v1",
    "planName": "Professional Monthly",
    "amount": 4900,
    "currency": "USD",
    "intervalUnit": "month",
    "intervalCount": 1,
    "type": 1,
    "description": "Professional plan with 10,000 API calls",
    "productName": "Professional Plan",
    "imageUrl": "https://cdn.example.com/pro-plan.png",
    "trialAmount": 0,
    "trialDurationTime": 1209600,
    "trialDemand": "paymentMethod",
    "metricLimits": [
      {
        "metricId": 100,
        "metricPlanLimit": 10000
      }
    ],
    "metricMeteredCharge": [
      {
        "metricId": 101,
        "aggregationProperty": "api_calls",
        "unitAmountCent": 10,
        "subAggregate": 0
      }
    ],
    "metadata": {
      "tier": "professional",
      "features": ["api_access", "analytics", "support"]
    }
  }'
```

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

### User Registration - Bash API Request

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Registers a new end-user account. Supports both individual and organization types. The process includes initial registration and email verification. Requires user details like email, password, name, country code, and phone. Returns user account details upon successful verification.

```bash
# Register individual user
curl -X POST https://api.unibee.dev/user/sso/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "password": "UserPass123!",
    "firstName": "Alice",
    "lastName": "Johnson",
    "type": 1,
    "countryCode": "US",
    "phone": "+1234567890"
  }'

# Response: { "code": 0, "message": "Verification email sent" }

# Verify registration
curl -X POST https://api.unibee.dev/user/sso/registerVerify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "verificationCode": "456789"
  }'

# Response with user account details
{
  "code": 0,
  "data": {
    "user": {
      "id": 5001,
      "email": "customer@example.com",
      "type": 1,
      "status": 0
    }
  }
```

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

### Merchant Registration - Bash API Request

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Registers a new merchant account. This process involves submitting initial registration details and then verifying the email with an OTP. Requires merchant details like name, email, password, and phone for registration, and email with OTP for verification. Returns merchant account details upon successful verification.

```bash
# Step 1: Submit registration
curl -X POST https://api.unibee.dev/merchant/sso/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@newcompany.com",
    "password": "SecurePass123!",
    "phone": "+1234567890",
    "userName": "janedoe"
  }'

# Response: { "code": 0, "message": "Verification email sent" }

# Step 2: Verify email with OTP
curl -X POST https://api.unibee.dev/merchant/sso/registerVerify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@newcompany.com",
    "verificationCode": "789012"
  }'

# Response
{
  "code": 0,
  "data": {
    "merchantMember": {
      "id": 1050,
      "merchantId": 525,
      "email": "jane@newcompany.com",
      "role": "Owner",
      "status": 1
    }
  }
```

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

### Discount Code Management

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Create and manage promotional discount codes with configurable types, amounts, and usage restrictions.

```APIDOC
## POST /merchant/discount/new_discount_code

### Description
Creates a new promotional discount code.

### Method
POST

### Endpoint
https://api.unibee.dev/merchant/discount/new_discount_code

### Parameters
#### Request Body
- **name** (string) - Required - The name of the discount campaign.
- **code** (string) - Required - The actual discount code to be used by customers.
- **billingType** (integer) - Required - Type of billing the discount applies to (1: One-time, 2: Recurring).
- **discountType** (integer) - Required - Type of discount (1: Percentage, 2: Fixed amount).
- **discountAmount** (number) - Required if discountType is Fixed amount - The fixed amount of the discount.
- **discountPercentage** (integer) - Required if discountType is Percentage - The discount percentage (e.g., 2000 for 20%).
- **currency** (string) - Optional - The currency for the discount if it's a fixed amount.
- **cycleLimit** (integer) - Optional - The number of billing cycles the discount can be applied to.
- **startTime** (integer) - Required - Unix timestamp for when the discount becomes active.
- **endTime** (integer) - Required - Unix timestamp for when the discount expires.
- **quantity** (integer) - Optional - The total number of times this discount code can be used.
- **planIds** (array of integers) - Optional - List of plan IDs this discount applies to.
- **userScope** (integer) - Required - Scope of users the discount applies to (1: New users only, 2: Renewals only, 3: All users).
- **metadata** (object) - Optional - Key-value pairs for additional discount information.

### Request Example
```json
{
  "name": "Spring Sale 2024",
  "code": "SPRING2024",
  "billingType": 1,
  "discountType": 1,
  "discountAmount": 0,
  "discountPercentage": 2000,
  "currency": "USD",
  "cycleLimit": 3,
  "startTime": 1704067200,
  "endTime": 1711929600,
  "quantity": 1000,
  "planIds": [2001, 2002],
  "userScope": 1,
  "metadata": {
    "campaign": "spring_promo",
    "channel": "email"
  }
}
```

### Response
#### Success Response (200)
- **discountCode** (object) - Details of the created discount code.
  - **id** (integer) - The internal ID of the discount code.
  - **code** (string) - The discount code.
  - **discountPercentage** (integer) - The discount percentage.
  - **status** (string) - The status of the discount code (e.g., 'active').
  - **quantity** (integer) - The total quantity allowed.
  - **usedQuantity** (integer) - The number of times the code has been used.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "discountCode": {
      "id": 3001,
      "code": "SPRING2024",
      "discountPercentage": 2000,
      "status": "active",
      "quantity": 1000,
      "usedQuantity": 0
    }
  }
}
```
```

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

### Create Discount Code - Unibee API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Generates a new discount code for promotional purposes. This endpoint allows for specifying discount type (percentage or fixed amount), cycle limits, usage quantity, and applicable plans. It also supports defining user scope for the discount.

```bash
curl -X POST https://api.unibee.dev/merchant/discount/new_discount_code \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Sale 2024",
    "code": "SPRING2024",
    "billingType": 1,
    "discountType": 1,
    "discountAmount": 0,
    "discountPercentage": 2000,
    "currency": "USD",
    "cycleLimit": 3,
    "startTime": 1704067200,
    "endTime": 1711929600,
    "quantity": 1000,
    "planIds": [2001, 2002],
    "userScope": 1,
    "metadata": {
      "campaign": "spring_promo",
      "channel": "email"
    }
  }'
```

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

### Update Subscription - Unibee API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Allows for upgrading or downgrading subscriptions, including plan changes, quantity adjustments, and addon management. Supports proration and immediate effect.

```bash
# Preview subscription update
curl -X POST https://api.unibee.dev/merchant/subscription/subscription_update_preview \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionId": "sub_1234567890",
    "newPlanId": 2002,
    "quantity": 2,
    "addonParams": [
      {
        "addonPlanId": 2051,
        "quantity": 1
      }
    ],
    "proration": true,
    "effectImmediate": true
  }'

# Response with proration invoice
{
  "code": 0,
  "data": {
    "currency": "USD",
    "totalAmount": 3200,
    "prorationAmount": 1500,
    "originAmount": 9900,
    "credit": 4800,
    "invoice": {
      "lines": [
        {
          "name": "Professional Monthly (unused)",
          "amount": -2450,
          "description": "Credit for 15 days"
        },
        {
          "name": "Enterprise Monthly",
          "amount": 9900,
          "quantity": 2
        }
      ]
    }
  }
}

# Apply subscription update
curl -X POST https://api.unibee.dev/merchant/subscription/subscription_update \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionId": "sub_1234567890",
    "newPlanId": 2002,
    "quantity": 2,
    "proration": true,
    "effectImmediate": true,
    "gatewayId": 1
  }'

# Response
{
  "code": 0,
  "data": {
    "subscription": {
      "subscriptionId": "sub_1234567890",
      "planId": 2002,
      "status": 2,
      "quantity": 2
    },
    "invoice": {
      "invoiceId": "inv_9876543210",
      "totalAmount": 3200,
      "status": "paid"
    }
  }
}
```

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

### User Management API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Endpoints for creating, searching, and managing end-user accounts with comprehensive profile data.

```APIDOC
## POST /merchant/user/new

### Description
Creates a new end-user account.

### Method
POST

### Endpoint
https://api.unibee.dev/merchant/user/new

### Parameters
#### Request Body
- **externalUserId** (string) - Required - The unique identifier for the user from an external system.
- **email** (string) - Required - The user's email address.
- **firstName** (string) - Optional - The user's first name.
- **lastName** (string) - Optional - The user's last name.
- **type** (integer) - Optional - The type of user (e.g., 1 for customer).
- **countryCode** (string) - Optional - The user's country code (e.g., 'US').
- **phone** (string) - Optional - The user's phone number.
- **address** (string) - Optional - The user's street address.
- **city** (string) - Optional - The user's city.
- **zipCode** (string) - Optional - The user's ZIP or postal code.
- **vatNumber** (string) - Optional - The user's VAT number.
- **companyName** (string) - Optional - The user's company name.
- **metadata** (object) - Optional - Key-value pairs for additional user information.

### Request Example
```json
{
  "externalUserId": "user_ext_12345",
  "email": "newuser@example.com",
  "firstName": "Robert",
  "lastName": "Brown",
  "type": 1,
  "countryCode": "US",
  "phone": "+1234567890",
  "address": "123 Main St",
  "city": "San Francisco",
  "zipCode": "94102",
  "vatNumber": "",
  "companyName": "",
  "metadata": {
    "source": "api_import",
    "segment": "enterprise"
  }
}
```

### Response
#### Success Response (200)
- **user** (object) - Contains user details.
  - **id** (integer) - The internal ID of the newly created user.
  - **externalUserId** (string) - The external user ID.
  - **email** (string) - The user's email.
  - **status** (integer) - The status of the user (e.g., 0 for active).

#### Response Example
```json
{
  "code": 0,
  "data": {
    "user": {
      "id": 5050,
      "externalUserId": "user_ext_12345",
      "email": "newuser@example.com",
      "status": 0
    }
  }
}
```

## POST /merchant/user/search

### Description
Searches for users based on a search key.

### Method
POST

### Endpoint
https://api.unibee.dev/merchant/user/search

### Parameters
#### Request Body
- **searchKey** (string) - Required - The key to search users by (e.g., name, email).

### Request Example
```json
{
  "searchKey": "robert"
}
```

### Response
#### Success Response (200)
- **users** (array) - A list of user objects matching the search criteria.
  - Each user object may contain:
    - **id** (integer) - User ID.
    - **email** (string) - User's email.
    - **firstName** (string) - User's first name.
    - **lastName** (string) - User's last name.
    - **subscriptions** (array) - List of user's subscriptions.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "users": [
      {
        "id": 5050,
        "email": "newuser@example.com",
        "firstName": "Robert",
        "lastName": "Brown",
        "subscriptions": [
          {
            "subscriptionId": "sub_abc123",
            "planName": "Professional Monthly",
            "status": 2
          }
        ]
      }
    ]
  }
}
```
```

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

### Payment Gateway Management API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Configure and manage payment gateway integrations, including API credentials and currency settings.

```APIDOC
## POST /merchant/gateway/setup

### Description
Sets up a new payment gateway integration or updates an existing one.

### Method
POST

### Endpoint
https://api.unibee.dev/merchant/gateway/setup

### Parameters
#### Request Body
- **gatewayName** (string) - Required - The name of the gateway (e.g., 'stripe', 'paypal').
- **gatewayKey** (object) - Required - API credentials for the gateway.
  - **apiKey** (string) - Required - The API key for the gateway.
  - **publishableKey** (string) - Optional - The publishable key for the gateway.
  - **webhookSecret** (string) - Optional - The webhook secret for the gateway.
- **minimumAmount** (integer) - Optional - The minimum transaction amount for this gateway.
- **currency** (array of strings) - Required - Supported currencies for this gateway (e.g., ['USD', 'EUR']).
- **countryConfig** (array of objects) - Optional - Configuration specific to countries.
  - **countryCode** (string) - Required - The country code.
  - **currency** (string) - Required - The currency for this country.

### Request Example
```json
{
  "gatewayName": "stripe",
  "gatewayKey": {
    "apiKey": "sk_test_51Ab...",
    "publishableKey": "pk_test_51Ab...",
    "webhookSecret": "whsec_..."
  },
  "minimumAmount": 50,
  "currency": ["USD", "EUR", "GBP"],
  "countryConfig": [
    {
      "countryCode": "US",
      "currency": "USD"
    }
  ]
}
```

### Response
#### Success Response (200)
- **gateway** (object) - Details of the configured gateway.
  - **gatewayId** (integer) - The internal ID of the gateway.
  - **gatewayName** (string) - The name of the gateway.
  - **status** (integer) - The status of the gateway (e.g., 1 for active).
  - **currencies** (array of strings) - List of supported currencies.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "gateway": {
      "gatewayId": 1,
      "gatewayName": "stripe",
      "status": 1,
      "currencies": ["USD", "EUR", "GBP"]
    }
  }
}
```

## GET /merchant/gateway/list

### Description
Retrieves a list of all configured payment gateways.

### Method
GET

### Endpoint
https://api.unibee.dev/merchant/gateway/list

### Parameters
No parameters required.

### Request Example
(No request body or parameters needed for this GET request)

### Response
#### Success Response (200)
- **gateways** (array) - A list of gateway objects.
  - Each gateway object contains:
    - **gatewayId** (integer) - The internal ID of the gateway.
    - **gatewayName** (string) - The name of the gateway.
    - **status** (integer) - The status of the gateway.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "gateways": [
      {
        "gatewayId": 1,
        "gatewayName": "stripe",
        "status": 1
      },
      {
        "gatewayId": 2,
        "gatewayName": "paypal",
        "status": 1
      }
    ]
  }
}
```
```

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

### Create User - Unibee API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Creates a new end-user account in the Unibee system. This endpoint allows for detailed user profile information, including contact details and metadata. The response includes the newly created user's ID and external user ID.

```bash
curl -X POST https://api.unibee.dev/merchant/user/new \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_ext_12345",
    "email": "newuser@example.com",
    "firstName": "Robert",
    "lastName": "Brown",
    "type": 1,
    "countryCode": "US",
    "phone": "+1234567890",
    "address": "123 Main St",
    "city": "San Francisco",
    "zipCode": "94102",
    "vatNumber": "",
    "companyName": "",
    "metadata": {
      "source": "api_import",
      "segment": "enterprise"
    }
  }'
```

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

### Configure Webhook Endpoint using Unibee API

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Manages webhook endpoints for receiving real-time event notifications from the Unibee platform. You can create new webhook endpoints by providing a `url` and a list of `events` to subscribe to. Additionally, you can list existing endpoints and retrieve a list of all available webhook events that can be subscribed to.

```bash
# Create webhook endpoint
curl -X POST https://api.unibee.dev/merchant/webhook/new_endpoint \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/unibee",
    "events": [
      "invoice.created",
      "invoice.paid",
      "invoice.failed",
      "subscription.created",
      "subscription.updated",
      "subscription.cancelled",
      "payment.success",
      "payment.failed",
      "payment.refund"
    ]
  }'
```

```bash
# List webhook endpoints
curl -X GET https://api.unibee.dev/merchant/webhook/endpoint_list \
  -H "Authorization: Bearer {token}"
```

```bash
# List available webhook events
curl -X GET https://api.unibee.dev/merchant/webhook/event_list \
  -H "Authorization: Bearer {token}"
```

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

### POST /merchant/plan/new

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Define recurring billing plan with pricing, intervals, trial periods, and metric limits. This endpoint allows merchants to create new subscription plans.

```APIDOC
## POST /merchant/plan/new

### Description
Define recurring billing plan with pricing, intervals, trial periods, and metric limits.

### Method
POST

### Endpoint
/merchant/plan/new

### Parameters
#### Request Body
- **externalPlanId** (string) - Required - Unique identifier for the plan.
- **planName** (string) - Required - Name of the plan.
- **amount** (integer) - Required - Billing amount in cents.
- **currency** (string) - Required - Currency code (e.g., USD).
- **intervalUnit** (string) - Required - Billing interval unit (e.g., 'day', 'week', 'month', 'year').
- **intervalCount** (integer) - Required - Number of interval units per billing cycle.
- **type** (integer) - Required - Plan type (e.g., 1 for recurring).
- **description** (string) - Optional - Description of the plan.
- **productName** (string) - Optional - Name of the associated product.
- **imageUrl** (string) - Optional - URL for the plan's image.
- **trialAmount** (integer) - Optional - Amount charged during the trial period (in cents).
- **trialDurationTime** (integer) - Optional - Duration of the trial period in seconds.
- **trialDemand** (string) - Optional - Requirement for trial (e.g., 'paymentMethod').
- **metricLimits** (array) - Optional - Limits for metered metrics.
  - **metricId** (integer) - Required - ID of the metric.
  - **metricPlanLimit** (integer) - Required - Limit for the metric within the plan.
- **metricMeteredCharge** (array) - Optional - Charges for metered metrics.
  - **metricId** (integer) - Required - ID of the metric.
  - **aggregationProperty** (string) - Required - Property for aggregation.
  - **unitAmountCent** (integer) - Required - Unit charge in cents.
  - **subAggregate** (integer) - Optional - Subscription aggregation setting.
- **metadata** (object) - Optional - Key-value pairs for custom data.

### Request Example
```json
{
  "externalPlanId": "pro-monthly-v1",
  "planName": "Professional Monthly",
  "amount": 4900,
  "currency": "USD",
  "intervalUnit": "month",
  "intervalCount": 1,
  "type": 1,
  "description": "Professional plan with 10,000 API calls",
  "productName": "Professional Plan",
  "imageUrl": "https://cdn.example.com/pro-plan.png",
  "trialAmount": 0,
  "trialDurationTime": 1209600,
  "trialDemand": "paymentMethod",
  "metricLimits": [
    {
      "metricId": 100,
      "metricPlanLimit": 10000
    }
  ],
  "metricMeteredCharge": [
    {
      "metricId": 101,
      "aggregationProperty": "api_calls",
      "unitAmountCent": 10,
      "subAggregate": 0
    }
  ],
  "metadata": {
    "tier": "professional",
    "features": ["api_access", "analytics", "support"]
  }
}
```

### Response
#### Success Response (200)
- **code** (integer) - Response code.
- **data** (object)
  - **plan** (object)
    - **id** (integer) - Unique ID of the created plan.
    - **planName** (string) - Name of the plan.
    - **amount** (integer) - Billing amount in cents.
    - **currency** (string) - Currency code.
    - **intervalUnit** (string) - Billing interval unit.
    - **intervalCount** (integer) - Interval count.
    - **status** (integer) - Plan status.
    - **publishStatus** (integer) - Publish status.
    - **type** (integer) - Plan type.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "plan": {
      "id": 2001,
      "planName": "Professional Monthly",
      "amount": 4900,
      "currency": "USD",
      "intervalUnit": "month",
      "intervalCount": 1,
      "status": 1,
      "publishStatus": 1,
      "type": 1
    }
  }
}
```
```

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

### Merchant Login with Password - Bash API Request

Source: https://context7.com/unibee-billing/unibee-api/llms.txt

Authenticates a merchant using email and password to obtain a JWT access token for the merchant portal. Requires email and password as JSON payload. Returns merchant details and a token upon success.

```bash
# Login request
curl -X POST https://api.unibee.dev/merchant/sso/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@company.com",
    "password": "SecurePass123!"
  }'

# Response
{
  "code": 0,
  "message": "success",
  "data": {
    "merchantMember": {
      "id": 1001,
      "merchantId": 500,
      "email": "admin@company.com",
      "firstName": "John",
      "lastName": "Smith",
      "role": "Owner",
      "status": 1
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

# Use token in subsequent requests
curl -X GET https://api.unibee.dev/merchant/profile_get \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```