Delete Merchant

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

DELETE /marketplace/merchants/{merchantId}/delete

cURL

curl -X DELETE https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/delete \
  -H "X-API-Key: pk_live_your_key"

Delete Merchant

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

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

Path Parameters

merchantId · string · required

The business ID of the sub-merchant to permanently delete.

Response

Successful Deletion (Stripe account also deleted)

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

Successful Deletion (Stripe account skipped due to balance)

{
  "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

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.

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

cURL

curl -X DELETE https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/delete \
  -H "X-API-Key: pk_live_your_key"