> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Merchant

> Permanently delete a sub-merchant and all their data from your marketplace.

# Delete Merchant

Permanently deletes a sub-merchant from your marketplace. This is a **destructive operation** that removes all business data associated with the merchant.

<Warning>
  This action cannot be undone. All merchant data including products, orders, transactions, and account information will be permanently deleted.
</Warning>

## Path Parameters

<ParamField path="merchantId" type="string" required>
  The business ID of the sub-merchant to permanently delete.
</ParamField>

## Response

### Successful Deletion (Stripe account also deleted)

```json theme={null}
{
  "success": true,
  "message": "Sub-merchant deleted successfully",
  "data": {
    "stripe_skipped": false,
    "stripe_balance": null
  }
}
```

### Successful Deletion (Stripe account skipped due to balance)

```json theme={null}
{
  "success": true,
  "message": "Sub-merchant deleted successfully. Note: Stripe account was not deleted because it has a balance of 150.00 USD. Please drain the balance manually before deleting the Stripe account.",
  "data": {
    "stripe_skipped": true,
    "stripe_balance": {
      "amount": 150.00,
      "currency": "USD"
    }
  }
}
```

## Response Fields

| Field                     | Type           | Description                                                                     |
| ------------------------- | -------------- | ------------------------------------------------------------------------------- |
| `stripe_skipped`          | boolean        | `true` if the Stripe connected account was not deleted due to remaining balance |
| `stripe_balance`          | object \| null | Balance details if Stripe deletion was skipped                                  |
| `stripe_balance.amount`   | number         | Remaining balance amount (in standard currency units, e.g., dollars not cents)  |
| `stripe_balance.currency` | string         | Currency code of the balance (e.g., `USD`, `GBP`)                               |

## Behavior

This endpoint performs the following operations:

1. **Validates Relationship** — Confirms the merchant belongs to your marketplace
2. **Checks Stripe Balance** — Retrieves the connected account's available and pending balance
3. **Deletes Stripe Account** — If balance is zero, permanently deletes the Stripe connected account
4. **Removes Marketplace Link** — Deletes the `MarketplaceMerchant` relationship record
5. **Clears Portfolio** — Removes marketplace references from the merchant's portfolio
6. **Deletes Business Data** — Removes all associated data including:
   * Products and variations
   * Orders and transactions
   * Wallet and withdrawal records
   * Customer data
   * Forms and responses
   * Website configurations
   * All other business-related records

### Stripe Account Handling

If the merchant has a Stripe connected account:

* **Balance = 0**: The Stripe account is permanently deleted
* **Balance > 0**: Stripe deletion is skipped, but all other data is still deleted. The response includes `stripe_skipped: true` and the balance details

<Note>
  If Stripe deletion is skipped due to balance, you should manually drain the balance (e.g., by processing a payout) before attempting to delete the Stripe account through the Stripe Dashboard.
</Note>

## Use Cases

* Removing a merchant who has violated marketplace terms
* Cleaning up test merchant accounts
* Merchant-requested account deletion for compliance (GDPR, etc.)

## Comparison with Remove Merchant

| Feature        | Remove Merchant      | Delete Merchant         |
| -------------- | -------------------- | ----------------------- |
| Reversible     | Yes (can reactivate) | No                      |
| Data preserved | Yes                  | No                      |
| Stripe account | Unchanged            | Deleted (if no balance) |
| Use case       | Temporary suspension | Permanent removal       |

## Error Codes

| Status | Error                                                  | Fix                                              |
| ------ | ------------------------------------------------------ | ------------------------------------------------ |
| `400`  | `Invalid merchant ID`                                  | Provide a valid numeric merchant ID              |
| `400`  | `Failed to delete merchant business data`              | Internal error during deletion — contact support |
| `401`  | `Unauthorized`                                         | Provide a valid `X-API-Key` header               |
| `403`  | `This endpoint is restricted to marketplace operators` | Your account must have marketplace mode enabled  |
| `404`  | `Merchant relationship not found`                      | The merchant is not linked to your marketplace   |

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/delete \
    -H "X-API-Key: pk_live_your_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/delete',
    {
      method: 'DELETE',
      headers: {
        'X-API-Key': 'pk_live_your_key'
      }
    }
  );

  const result = await response.json();

  if (result.data.stripe_skipped) {
    console.log(`Stripe account has balance: ${result.data.stripe_balance.amount} ${result.data.stripe_balance.currency}`);
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/delete',
      headers={'X-API-Key': 'pk_live_your_key'}
  )

  result = response.json()

  if result['data']['stripe_skipped']:
      balance = result['data']['stripe_balance']
      print(f"Stripe account has balance: {balance['amount']} {balance['currency']}")
  ```
</RequestExample>