---
title: "Create Merchant"
method: POST
path: "/merchants"
tags: ["Merchants"]
---

# Create Merchant

`POST /merchants`

## Request

- Base URL: `https://app-sandbox.resolvepay.com/api`
- URL: `https://app-sandbox.resolvepay.com/api/merchants`
- Auth: one of:
  - HTTP bearer
  - HTTP basic
- TypeScript: <https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference/docs/merchants/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a sub-merchant under the authenticated partner and starts underwriting lifecycle tracking.

For the **partner API** contract, `id` is server-managed and is not accepted in the request payload.
Resolve derives/assigns the merchant identifier from merchant naming inputs (`dba_name` or `legal_business_name`) with random alphanumeric fallback for collisions.

Core merchant validation includes:
- `business_phone` must be a valid US phone number
- `formation_state` must map to a valid US state
- US business addresses validate `state` and `postal_code`
- beneficial owner US addresses validate `state` and `postal_code`
- `authorized_signer.phone`, when provided, must be a valid US phone number
- `ein` must be a valid EIN format
- banking fields validate account-number shape and ABA routing number format
- `bank_account_number` must be different from `bank_routing_number`

This endpoint also supports optional inline document URL ingestion. If document arrays are provided
(`bank_statements`, `financial_statements`, `credit_references`, `personal_guarantee`, `other_documents`),
Resolve queues `download_url` ingestion jobs equivalent to the document endpoint.

Inline document requests require:
- `filename` with an extension
- supported `filetype` for the merchant underwriting document profile
- `download_url` using `http` or `https`
- matching filename extension and `filetype`

Merchant creation is not rolled back for inline document ingestion failures.

Inline download dispatch is performed after database commit. Dispatch failures are surfaced per-item in
`document_ingestion.results`, and the affected merchant document/file metadata is marked failed even though
the merchant and some/all document rows were already persisted.

## Request body

- CreateMerchantRequest
  - `reference_id` string, nullable: Partner-supplied identifier for this merchant in your own system. Stored as provided and returned on every merchant response. Filter on it with `filter[reference_id][eq]=<value>` when listing merchants. Values are not required to be unique across your merchants, are limited to 255 characters, and may not be blank. Send `null` to clear a previously stored value.
  - `legal_business_name` string, required
  - `business_address` Address, required
    - `line1` string, required
    - `line2` string, nullable
    - `city` string, required
    - `state` string, required
    - `postal_code` string, required
    - `country` string, required
  - `business_email` string, email, required
  - `business_phone` string, required: Business phone number. Must be a valid US phone number and is normalized to E.164.
  - `entity_type` 'corporation' | 'llc' | 'sole_proprietorship' | 'partnership' | 'non_profit', required
  - `formation_state` string, required: Business formation state. Must map to a valid US state and is normalized to the state code.
  - `ein` string, required: Employer Identification Number. Must be a valid EIN format.
  - `dba_name` string
  - `annual_revenue` integer
  - `years_in_business` integer
  - `industry` string
  - `business_description` string
  - `website` string, uri
  - `estimated_monthly_net_terms_volume` integer
  - `existing_net_terms_info` object
  - `beneficial_owners` BeneficialOwner[]: Initial beneficial owner list.
    - `first_name` string, required
    - `last_name` string, required
    - `date_of_birth` string, date, required
    - `address` Address, required
      - `line1` string, required
      - `line2` string, nullable
      - `city` string, required
      - `state` string, required
      - `postal_code` string, required
      - `country` string, required
    - `ssn_last_4` string, required
    - `ownership_percentage` number, double
  - `authorized_signer` AuthorizedSigner
    - `first_name` string
    - `last_name` string
    - `email` string, email
    - `title` string
    - `phone` string
  - `plaid_access_token` string: Plaid access token when a bank connection has already been established.
  - `bank_account_number` string: Bank account number. Must satisfy Resolve account-number validation and must be different from `bank_routing_number`.
  - `bank_routing_number` string: ABA routing number. Must be a valid routing number.
  - `metadata` object
  - `bank_statements` InlineDocumentDownloadRequest[]: Optional document ingestion on merchant create. Each item queues a background download job (equivalent to calling the document endpoint with `download_url`).
    - `filename` string, required: Original filename for the remote file. The filename must include an extension, and that extension must match `filetype`.
    - `filetype` string, required: MIME type for the remote file. Must be a supported MIME type for the merchant underwriting document validation profile.
    - `download_url` string, uri, required: Remote file URL. Only `http` and `https` URLs are accepted.
  - `financial_statements` InlineDocumentDownloadRequest[]: Optional inline `financial_statements` document ingestion requests.
    - `filename` string, required: Original filename for the remote file. The filename must include an extension, and that extension must match `filetype`.
    - `filetype` string, required: MIME type for the remote file. Must be a supported MIME type for the merchant underwriting document validation profile.
    - `download_url` string, uri, required: Remote file URL. Only `http` and `https` URLs are accepted.
  - `credit_references` InlineDocumentDownloadRequest[]: Optional inline `credit_references` document ingestion requests.
    - `filename` string, required: Original filename for the remote file. The filename must include an extension, and that extension must match `filetype`.
    - `filetype` string, required: MIME type for the remote file. Must be a supported MIME type for the merchant underwriting document validation profile.
    - `download_url` string, uri, required: Remote file URL. Only `http` and `https` URLs are accepted.
  - `personal_guarantee` InlineDocumentDownloadRequest[]: Optional inline `personal_guarantee` document ingestion requests.
    - `filename` string, required: Original filename for the remote file. The filename must include an extension, and that extension must match `filetype`.
    - `filetype` string, required: MIME type for the remote file. Must be a supported MIME type for the merchant underwriting document validation profile.
    - `download_url` string, uri, required: Remote file URL. Only `http` and `https` URLs are accepted.
  - `other_documents` InlineDocumentDownloadRequest[]: Optional inline `other` document ingestion requests.
    - `filename` string, required: Original filename for the remote file. The filename must include an extension, and that extension must match `filetype`.
    - `filetype` string, required: MIME type for the remote file. Must be a supported MIME type for the merchant underwriting document validation profile.
    - `download_url` string, uri, required: Remote file URL. Only `http` and `https` URLs are accepted.

## Response `200`

A merchant object.

- Merchant
  - `id` string: Resolve merchant identifier (lowercase alphanumeric). For partner API create flows, ID assignment behavior is: - Resolve may derive a human-friendly alphanumeric candidate from merchant naming fields. - If the candidate collides with an existing merchant ID, Resolve generates a random lowercase alphanumeric ID.
  - `reference_id` string, nullable: Partner-supplied identifier for this merchant in your own system. `null` when never set.
  - `legal_business_name` string
  - `dba_name` string, nullable
  - `business_address` Address
    - `line1` string, required
    - `line2` string, nullable
    - `city` string, required
    - `state` string, required
    - `postal_code` string, required
    - `country` string, required
  - `business_email` string, email
  - `business_phone` string
  - `entity_type` 'corporation' | 'llc' | 'sole_proprietorship' | 'partnership' | 'non_profit'
  - `formation_state` string
  - `industry` string, nullable
  - `website` string, uri, nullable
  - `underwriting_status` string: Current underwriting lifecycle status for the merchant.
  - `seller_amount_approved` integer, nullable: Merchant approved limit (MAL), when available.
  - `active_subscription` object, nullable
    - `id` string
    - `tier` string
  - `metadata` object
  - `document_ingestion` DocumentIngestionSummary
    - `requested_count` integer
    - `queued_count` integer
    - `failed_count` integer
    - `results` DocumentIngestionResult[]
      - `document_id` string, nullable
      - `document_type` 'bank_statements' | 'financial_statements' | 'credit_references' | 'personal_guarantee' | 'other'
      - `filename` string
      - `download_url` string, uri
      - `status` 'queued' | 'failed'
      - `error_code` string, nullable
      - `error_message` string, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Bad request error
- `401`: Unauthorized error
- `404`: Not found error
- `429`: Rate limit error

---

[API](https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference.md) - [All operations](https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference/revisions/5a1c75b8b404?raw)