# Create a merchant

> `POST https://api.kustom.co/accountmanagement/v1/merchants/`

Creates a new merchant account. Returns the merchant ID, creation timestamp, and initial API credentials.

## Request body

`application/json`

- `email` (string, required) — Primary contact email for the merchant.
- `phone` (string) — Primary contact phone number.
- `type` (string, required) — Merchant type. Enum: `ESTABLISHED`, `NEW`.
- `country` (string, required) — Two-letter ISO 3166-1 alpha-2 country code.
- `price_plan` (string, required) — The pricing plan assigned to this merchant.
- `platform` (string) — E-commerce platform used by the merchant.
- `special_offer_id` (string) — ID of a special pricing offer, if applicable.
- `custom_data` (object) — Arbitrary key-value metadata.
  - `key` (any) — Any additional property. The key is free-form; the value has this shape.
- `business_information` (object, required) — Business details for the merchant.
  - `organization_is_registered` (boolean) — Whether the organization is officially registered.
  - `organization_entity_type` (string) — Legal entity type (e.g. AB, GmbH, Ltd).
  - `organization_name` (string) — Legal name of the organization.
  - `organization_registration_id` (string) — Official registration number.
  - `organization_registration_authority` (string) — Registration authority (e.g. Companies House, Bolagsverket).
  - `vat_id` (string) — VAT identification number.
  - `subject_to_vat` (boolean) — Whether the organization is subject to VAT.
  - `registered_address` (object) — A physical address.
    - `street_address` (string) — Primary street address.
    - `street_address2` (string) — Secondary street address (apt, suite, etc.).
    - `postal_code` (string) — Postal or ZIP code.
    - `city` (string) — City name.
    - `region` (string) — State, province, or region.
    - `country` (string) — Two-letter ISO 3166-1 alpha-2 country code.
  - `operating_address` (object) — A physical address. Same shape as `registered_address`.
  - `owner` (object) — A business owner or managing director.
    - `given_name` (string) — First name.
    - `family_name` (string) — Last name.
    - `date_of_birth` (string) — Date of birth (YYYY-MM-DD).
    - `title` (string) — Job title or role.
    - `managing_director` (boolean) — Whether this person is a managing director.
    - `personal_id` (string) — National personal identification number.
    - `street_address` (string)
    - `street_address2` (string)
    - `postal_code` (string)
    - `city` (string)
    - `region` (string)
    - `country` (string) — Two-letter ISO 3166-1 alpha-2 country code.
  - `owners[]` (array<object>) — List of business owners. Same shape as `owner`.
- `store_information` (object, required) — Container for merchant stores.
  - `stores[]` (array<object>, required) — List of stores (at least one required).
    - `country` (string) — Two-letter ISO 3166-1 alpha-2 country code.
    - `store_name` (string) — Display name of the store.
    - `organization_category` (string) — Business category.
    - `merchant_category_code` (string) — MCC code.
    - `homepage_url` (string) — Store website URL.
    - `icon_url` (string) — URL to the store icon.
    - `logo_url` (string) — URL to the store logo.
    - `support_email` (string) — Customer support email.
    - `support_phone` (string) — Customer support phone number.
- `bank_accounts[]` (array<object>, required) — List of bank accounts for settlements (at least one required).
  - `account_number` (string) — Bank account number (IBAN or local format).
  - `account_type` (string) — Account type (e.g. CHECKING, SAVINGS).
  - `account_holder` (string) — Name of the account holder.
  - `country` (string) — Two-letter country code for the bank.
  - `currency_code` (string) — Three-letter ISO 4217 currency code.
  - `routing_number` (string) — Bank routing or sort code.
  - `is_default` (boolean) — Whether this is the default settlement account.
- `stakeholders[]` (array<object>, required) — List of stakeholders (at least one required).
  - `type` (string) — Stakeholder type.
  - `given_name` (string) — First name.
  - `family_name` (string) — Last name.
  - `email` (string) — Email address.
  - `phone` (string) — Phone number.
  - `address` (object) — A physical address.
    - `street_address` (string) — Primary street address.
    - `street_address2` (string) — Secondary street address (apt, suite, etc.).
    - `postal_code` (string) — Postal or ZIP code.
    - `city` (string) — City name.
    - `region` (string) — State, province, or region.
    - `country` (string) — Two-letter ISO 3166-1 alpha-2 country code.
  - `company_name` (string) — Company name (if applicable).
  - `registration_id` (string) — Registration ID (if applicable).

### Example request

```json
{
  "email": "<email>",
  "phone": "<string>",
  "type": "ESTABLISHED",
  "country": "<string>",
  "price_plan": "<string>",
  "platform": "<string>",
  "special_offer_id": "<string>",
  "custom_data": {
    "key": "<string>"
  },
  "business_information": {
    "organization_is_registered": false,
    "organization_entity_type": "<string>",
    "organization_name": "<string>",
    "organization_registration_id": "<string>",
    "organization_registration_authority": "<string>",
    "vat_id": "<string>",
    "subject_to_vat": false,
    "registered_address": {
      "street_address": "<string>",
      "street_address2": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "region": "<string>",
      "country": "<string>"
    },
    "operating_address": {
      "street_address": "<string>",
      "street_address2": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "region": "<string>",
      "country": "<string>"
    },
    "owner": {
      "given_name": "<string>",
      "family_name": "<string>",
      "date_of_birth": "<date>",
      "title": "<string>",
      "managing_director": false,
      "personal_id": "<string>",
      "street_address": "<string>",
      "street_address2": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "region": "<string>",
      "country": "<string>"
    },
    "owners": [
      {
        "given_name": "<string>",
        "family_name": "<string>",
        "date_of_birth": "<date>",
        "title": "<string>",
        "managing_director": false,
        "personal_id": "<string>",
        "street_address": "<string>",
        "street_address2": "<string>",
        "postal_code": "<string>",
        "city": "<string>",
        "region": "<string>",
        "country": "<string>"
      }
    ]
  },
  "store_information": {
    "stores": [
      {
        "country": "<string>",
        "store_name": "<string>",
        "organization_category": "<string>",
        "merchant_category_code": "<string>",
        "homepage_url": "<string>",
        "icon_url": "<string>",
        "logo_url": "<string>",
        "support_email": "<string>",
        "support_phone": "<string>"
      }
    ]
  },
  "bank_accounts": [
    {
      "account_number": "<string>",
      "account_type": "<string>",
      "account_holder": "<string>",
      "country": "<string>",
      "currency_code": "<string>",
      "routing_number": "<string>",
      "is_default": false
    }
  ],
  "stakeholders": [
    {
      "type": "<string>",
      "given_name": "<string>",
      "family_name": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "address": {
        "street_address": "<string>",
        "street_address2": "<string>",
        "postal_code": "<string>",
        "city": "<string>",
        "region": "<string>",
        "country": "<string>"
      },
      "company_name": "<string>",
      "registration_id": "<string>"
    }
  ]
}
```

## Responses

### 200

Merchant successfully created.

`application/json`

- `merchant_id` (string, required) — The unique Kustom merchant identifier.
- `created_at` (string, required) — Timestamp when the merchant was created.
- `credentials` (object, required) — Merchant API credentials.
  - `username` (string, required) — The API username for the merchant.
  - `password` (string, required) — The API password for the merchant.

```json
{
  "merchant_id": "<string>",
  "created_at": "<date-time>",
  "credentials": {
    "username": "<string>",
    "password": "<string>"
  }
}
```

### 400

Invalid request payload.

### 401

Unauthorized — missing or invalid access token.