Import Merchants

Bulk-onboard sub-merchants: for each entry, creates a new Khaime account if the email doesn’t exist yet, or links the existing account if it does. Combines what Create Merchant and Link Merchant do individually, per row.

This endpoint always returns 201, even if every single entry fails. There is no top-level error status for partial or total per-entry failure — you must inspect data.summary.failed / data.results.failed to know what actually happened. Don’t treat a 201 as “all merchants imported successfully.”

Request Body

array

required

Non-empty array, maximum 100 entries per request.

Show Merchant entry fields

string

required

Required for every entry. If missing or not a string, that entry is recorded in results.failed — it does not fail the whole request.

string

Required only when no existing Khaime account matches business_email (i.e. this entry will create a new account). Omit it when linking an existing account.

string

Optional, used only on account creation.

string

Optional, used only on account creation.

number

Optional decimal between 0 and 1 for this entry. Same inheritance behavior as Link Merchant when omitted.

Response

{
  "success": true,
  "message": "Import complete: 1 created, 1 linked, 0 skipped, 1 failed",
  "data": {
    "summary": { "total": 3, "created": 1, "linked": 1, "skipped": 0, "failed": 1, "succeeded": 2 },
    "results": {
      "created": [
        {
          "email": "new@biz.com",
          "merchant_id": 900,
          "business_name": "New Biz",
          "subdomain": "new-biz",
          "temporary_password": "a1b2c3d4e5f6a1b2c3d4e5f6"
        }
      ],
      "linked": [
        { "email": "existing@biz.com", "merchant_id": 55, "business_name": "Existing Biz", "action": "linked" }
      ],
      "skipped": [
        { "email": "already-active@biz.com", "merchant_id": 33, "business_name": "Already Active Biz", "reason": "Already linked and active" }
      ],
      "failed": [
        { "email": "bad@biz.com", "reason": "commission_rate must be a decimal between 0 and 1" }
      ]
    }
  }
}

temporary_password is returned in plaintext for every newly created account. This is the account’s real login password — treat the response as sensitive, don’t log it in plaintext analytics or client-visible logs, and prompt the merchant to change it on first login.

`linked` entries: `action` is `"linked"` or `"reactivated"`

An entry lands in results.linked in two different situations, distinguished by action:

"linked" — an existing Khaime account with no prior relationship to your marketplace was linked for the first time.
"reactivated" — the account had a previously suspended relationship with your marketplace, now reactivated.

An entry with an existing active relationship is not re-linked at all — it goes to results.skipped instead (see below), not results.linked.

`skipped` entries

An entry lands here only for one reason today: reason: "Already linked and active" — the email already has an active relationship in your marketplace, so nothing changed.

Per-entry failure reasons

Each item in results.failed has a reason string, one of:

"business_email is required" — missing or non-string email
"commission_rate must be a decimal between 0 and 1"
"Cannot link your own account as a sub-merchant" — entry’s email matches your own operator account
"business_name is required when creating a new account (no existing Khaime account found)"
any other caught exception message (generic, not enumerable)

Error Codes

Status	Error Code	Cause
`403`	`AUTH_PERMISSION_DENIED`	Your business isn’t a marketplace operator.
`400`	`VALIDATION_FAILED`	`merchants` missing, not an array, empty, or exceeds 100 entries.
`400`	`INTERNAL_ERROR`	Unhandled top-level error (individual entry failures do not trigger this — see per-entry `failed` array above).

curl -X POST https://api.khaime.com/api/v1/partner/marketplace/merchants/import \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "merchants": [
      { "business_email": "new@biz.com", "business_name": "New Biz", "commission_rate": 0.1 },
      { "business_email": "existing@biz.com" }
    ]
  }'

API Reference

Account

Products & Pricing

Payments

Subscriptions

Marketplace

Import Merchants

Import Merchants

Request Body

Response

`linked` entries: `action` is `"linked"` or `"reactivated"`

`skipped` entries

Per-entry failure reasons

Error Codes

​Import Merchants

​Request Body

​Response

​linked entries: action is "linked" or "reactivated"

​skipped entries

​Per-entry failure reasons

​Error Codes

Import Merchants

Request Body

Response

`linked` entries: `action` is `"linked"` or `"reactivated"`

`skipped` entries

Per-entry failure reasons

Error Codes