Marketplace
Create Merchant
Add a new sub-merchant to your marketplace.
POST
Intro
Creates a Khaime business account for a sub-merchant and links it to your marketplace in one call. If the email you send already belongs to a Khaime account, that account is linked instead of a new one being created.Context
This is the “I have a new merchant who has never used Khaime” path in the merchant lifecycle: Create Merchant → Get Merchant Details → Update Merchant → Remove Merchant. If the merchant already has a Khaime account, use Link Merchant instead — it skips account creation and only attaches the relationship. Onboarding many merchants at once? Import Merchants does the create-or-link decision per row for up to 100 entries. Only businesses with marketplace mode enabled can call this endpoint — see Setup Marketplace for how that’s provisioned. Once a merchant is linked, their products can be managed through the Marketplace Products endpoints and charged viasub_merchant_id on Create Charge.
Hows
Request Body
string
required
Sub-merchant’s business name.
string
required
Sub-merchant’s email address. Must not already belong to a Khaime account — if it does, this call fails; use Link Merchant for existing accounts instead.
string
Password for the new account. If omitted, a temporary password is auto-generated and returned in the response.
string
Sub-merchant’s phone number.
string
Sub-merchant’s country.
number
Override the default marketplace commission for this merchant. Value between
0 and 1 (e.g., 0.08 for 8%). If omitted, the merchant inherits your marketplace’s default rate dynamically — if you later change the default via Update Marketplace Settings, this merchant’s effective rate changes with it.Response
temporary_password is only returned when the system auto-generates a password (i.e., business_password was not provided). Share this with the merchant so they can log in and change it — it will not be shown again.Error Codes
Whys
Merchants who join a marketplace often have no prior relationship with Khaime, so the operator needs a way to provision an account on their behalf rather than sending every merchant through Khaime’s own signup flow. Bundling account creation and marketplace linking into one call — inside one database transaction — avoids a half-onboarded state where an account exists but isn’t actually attached to the marketplace. Auto-generating a password when none is supplied means operators integrating this into a bulk-onboarding flow don’t need to invent and track passwords themselves; the merchant changes it on first login.Why nots
This endpoint always creates (or requires creating) a new Khaime account — it does not attach to an existing one. If the email is already registered, the call fails withVALIDATION_FAILED rather than silently linking; use Link Merchant when the account already exists, or Import Merchants if you don’t know in advance which merchants are new versus existing.
Marketplace mode itself cannot be turned on from this endpoint or any partner API call — it’s provisioned by Khaime, not self-serve. See Setup Marketplace.
The merchant is created without a Khaime storefront/website — this endpoint is meant for merchants who sell exclusively through your marketplace integration, not through a Khaime-hosted store.