Skip to main content
DELETE

​
Intro

Suspends a sub-merchant from your marketplace — the relationship is marked suspended, not deleted, and can be relinked later.

​
Context

The suspend step of the merchant lifecycle: Create Merchant or Link Merchant attach a merchant, Get Merchant Details and Update Merchant manage them while active, and this endpoint detaches them without destroying data. To bring a suspended merchant back, call Link Merchant again with the same email — it detects the suspended relationship and reactivates it (or Import Merchants does the same in bulk).

​
Hows

​
Path Parameters

​
string
required
The business ID of the sub-merchant to suspend.

​
Response

​
Behavior

Only merchants with an active relationship to your marketplace can be suspended. The following happens:
  • The marketplace-merchant relationship’s status is set to suspended.
  • The merchant’s marketplace assignment and commission override on their own account are cleared, so they no longer read back as belonging to your marketplace elsewhere in the API — reactivating via Link Merchant restores both.
The merchant’s Khaime account, products, and transaction history are not affected or deleted.
To permanently delete a sub-merchant’s data rather than suspend the relationship, a separate destructive delete endpoint exists at DELETE /marketplace/merchants/{merchantId}/delete. Reach for it only when you mean to permanently remove the merchant, not for routine deactivation.

​
Error Codes

​
Whys

Suspension rather than deletion is the default because removing a merchant from a marketplace is usually a business decision (they left, they’re paused, the relationship needs renegotiating), not a request to erase their history. Keeping the merchant’s account, products, and transactions intact means a suspension can be reversed cleanly, and past transactions remain auditable even after the relationship ends.

​
Why nots

This does not delete the merchant’s Khaime account, products, or past transactions — it only detaches the marketplace relationship. It does not work on a relationship that’s already suspended or was never linked — you’ll get BUSINESS_NOT_FOUND in both cases, since suspending twice isn’t a meaningful operation. If you need the merchant’s data permanently gone (not just detached), that’s a separate, explicitly destructive operation — not this endpoint.