# Pre-provisioning Merchant Data

Violet's Onboarding APIs let Channels pre-provision merchant data **before** a merchant completes the Violet Connect flow. These APIs allow you to pass metadata—such as your internal Merchant ID or external Payment Provider credentials—to programmatically associate merchant and payout details prior to onboarding a Merchant via Violet Connect.

### Shopify Merchants: Two Pre-Registration Methods

Since Shopify now requires merchants to use single-merchant custom apps, Violet provides two ways to pre-register merchants before they complete Violet Connect:

1. **Channel Dashboard UI** (Recommended for most channels): Use the Pre-Registered tab to add merchants manually with their custom app credentials. See [Shopify Custom App Migration Guide](/prism/violet-connect/guides/shopify-custom-app-migration.md)
2. **Onboarding APIs** (Recommended for programmatic integrations): Use the APIs documented below to pre-provision merchant data at scale using your backend systems.

Both methods result in the same outcome - merchants can connect with pre-filled credentials and streamlined flows. Choose the method that fits your integration architecture.

## What Are Onboarding APIs?

The Onboarding APIs are designed to:

* Pass data about merchants in your system *before* they formally exist in Violet (i.e. prior to going through Violet Connect).
* Associate internal merchant identifiers (`channel_merchant_id`) with Violet merchants
* Attach metadata such as payout account credentials (e.g. Stripe Account IDs) to be used by Violet during Violet Connect onboarding.
* Retrieve and update onboarding records during the pre-connect phase

Once a merchant completes Violet Connect, this onboarding data is automatically merged into the Violet Merchant record. From that point on, use [Merchant APIs](/api-reference/merchants/merchant/get-merchants.md) to interact with merchant data.

#### Onboarding Flow Diagram

This is a sample flow of how our Onboarding APIs interact with Violet Connect during Merchant Onboarding.

{% @mermaid/diagram content="sequenceDiagram
participant Channel
participant Merchant
participant Violet
participant Stripe

```
Channel->>Violet: POST /v1/merchants/onboard (channel_merchant_id + payout details)
Violet->>Violet: Store Onboarding Record (merchant_onboarding_id generated)
Violet->>Channel: Return Merchant Onboarding with merchant_onboarding_id
Merchant->>Channel: Begins onboarding flow
Channel->>Merchant: Redirect to Violet Connect URL (+ merchant_onboarding_id param)
Merchant->>Violet: Completes onboarding via Connect
Violet->>Violet: Fetch Merchant Onboarding Record to associate pre-existing data with new Violet Merchant
Violet->>Stripe: (Optional) Create Payout Account if Payout Details present in Merchant Onboarding record
Stripe->>Violet: Stripe Express Account for Merchant in Channel Stripe Platform Account
Violet->>Violet: Merge Onboarding Record Violet Merchant + Payout Account
Violet-->>Channel: Emit MERCHANT_CONNECTED webhook
Violet->>Merchant: Complete Violet Connect Onboarding Flow
Merchant->>Channel: Redirected back to Channel" %}
```

### Types of Onboarding Data

#### **Merchant Identity**

Use `channel_merchant_id` to uniquely identify the merchant in your system. This ensures that the merchant onboarding in your system is correctly linked to their Violet Connect onboarding process.

**Example use case:**

* Matching a merchant who’s onboarded to your marketplace with their corresponding record in Violet

#### **Payout Data**

You can attach payout account credentials such as a Stripe Connect `account_id` before the merchant is created in Violet. If you sent the `channel_merchant_id` or `merchant_onboarding_id` to Violet Connect while onboarding this merchant, Violet will automatically create a Violet Payout Account associated with this Stripe Account during onboarding.

### Available Onboarding APIs

Violet provides the following endpoints to manage onboarding records:

| Endpoint                                        | Method | Purpose                                           |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| `/v1/merchants/onboard`                         | `POST` | Create a new onboarding record                    |
| `/v1/merchants/onboard/:merchant_onboarding_id` | `PUT`  | Update by onboarding record ID                    |
| `/v1/merchants/onboard/:merchant_onboarding_id` | `GET`  | Get a specific onboarding record                  |
| `/v1/merchants/onboard`                         | `GET`  | List all onboarding records currently in progress |

Once onboarding is complete, these records are removed and replaced by standard Merchant and Payout Account objects.

Each of these APIs returns a `MerchantOnboardingRecord`. The `merchant_onboarding_id` can be passed into Violet Connect to tell Violet to use the pre-provided data during onboarding.

```json
{
  "merchant_onboarding_id": 10000,
  "channel_merchant_id": "chnl_123456789",
  "app_id": 10193,
  "date_created": "2024-06-24T15:30:55+0000",
  "date_last_modified": "2024-06-24T15:30:57+0000"
}
```

| Field                    | Type    | Description                                                                                                                                            |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `merchant_onboarding_id` | Integer | Unique identifier for the onboarding record generated by Violet. Used to track and update merchant data that will be used by Violet during onboarding. |
| `channel_merchant_id`    | String  | Unique identifier for the merchant in your system. Used to link your merchant record with the one created in Violet.                                   |
| `app_id`                 | Integer | Identifier for your application within Violet. Determines which channel or integration this onboarding record is associated with.                      |
| `date_created`           | Date    | Timestamp indicating when the onboarding record was first created. Format: `YYYY-MM-DDTHH:MM:SS+ZZZZ`                                                  |
| `date_last_modified`     | Date    | Timestamp of the most recent update to the onboarding record. Format: `YYYY-MM-DDTHH:MM:SS+ZZZZ`                                                       |

#### Create Merchant Onboarding Record

Creates a new onboarding record with a unique identifier for the merchant in your system.

```json
POST /v1/merchants/onboard

{
  "channel_merchant_id": "chnl_123456789"
}
```

Request Body Parameters

| Field                 | Required | Description                                                  |
| --------------------- | -------- | ------------------------------------------------------------ |
| `channel_merchant_id` | Yes      | Unique identifier of this merchant in the channel’s systems. |

<details>

<summary>Sample Response</summary>

```json
{
  "merchant_onboarding_id": 10000,
  "channel_merchant_id": "chnl_123456789",
  "app_id": 10385,
  "date_created": "2024-06-24T15:30:55+0000",
  "date_last_modified": "2024-06-24T15:30:57+0000"
}
```

</details>

**Optional: Adding Payout Account Data**

You can include payout account information (e.g. a Stripe Connect ID) when creating a merchant onboarding record to associate a pre-existing Payment Provider account with a Violet Merchant during Violet Connect.

<details>

<summary>Sample Request</summary>

```json
POST /v1/merchants/onboard

{
  "channel_merchant_id": "chnl_123456789",
  "payout_details": {
    "payment_provider": "STRIPE",
    "payment_provider_metadata": {
      "stripe_account_id": "acct_123456789"
    }
  }
}
```

</details>

**Payout Detail Parameters**

| Field                       | Required | Description                                                                                                                                                               |
| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payout_details`            | Yes      | Wrapper object that contains information needed for payout account onboarding.                                                                                            |
| `payment_provider`          | Yes      | Payment provider that this underlying payout account was created on. The metadata fields correspond to the payment provider.                                              |
| `payment_provider_metadata` | Yes      | Wrapper object that contains information specifically required to onboard payout accounts for the given payment provider. This field can also be passed in as `metadata`. |
| `stripe_account_id`         | Yes      | Account identifier of this merchant’s Stripe Connect account in Stripe’s systems.                                                                                         |

{% hint style="info" %}
If your Stripe Platform Account has not been set up with Violet, Violet will not subscribe to any webhook updates sent from Stripe for the provided Stripe Connect account.
{% endhint %}

<details>

<summary>Sample Response</summary>

```json
{
  "merchant_onboarding_id": 10000,
  "channel_merchant_id": "chnl_123456789",
  "app_id": 10385,
  "payout_details": {
    "payment_provider": "STRIPE",
    "payment_provider_metadata": {
      "stripe_account_id": "acct_123456789"
    }
  },
  "date_created": "2024-06-24T15:30:55+0000",
  "date_last_modified": "2024-06-24T15:30:57+0000"
}
```

</details>

#### Update Merchant Onboarding Record

Updates an onboarding record using the `merchant_onboarding_id`.

```jsx
PUT /v1/merchants/onboard/:merchant_onboarding_id
```

<details>

<summary>Sample Request</summary>

This call will update an existing Merchant Onboarding record with additional Payout Details:

```json
 PUT /v1/merchants/onboard/merchant_onboarding_id/10000

{
  "channel_merchant_id": "chnl_999999999",
  "payout_details": {
    "payment_provider": "STRIPE",
    "payment_provider_metadata": {
      "stripe_account_id": "acct_123456789"
    }
  }
}
```

</details>

<details>

<summary>Sample Response</summary>

```json
{
  "merchant_onboarding_id": 10000,
  "channel_merchant_id": "chnl_999999999",
  "app_id": 10385,
  "payout_details": {
    "payment_provider": "STRIPE",
    "payment_provider_metadata": {
      "stripe_account_id": "acct_123456789"
    }
  },
  "date_created": "2024-06-24T15:30:55+0000",
  "date_last_modified": "2024-06-24T15:30:57+0000"
}
```

</details>

**Potential Errors**

<table><thead><tr><th>Request</th><th width="90.16015625">Error Code</th><th width="347.59375">Error Title</th><th width="224.1796875">Error Message</th><th width="197.7421875">Reason</th><th width="222.80078125">How to Fix</th></tr></thead><tbody><tr><td><code>PUT</code></td><td>4429</td><td>merchant_onboarding_record_not_found</td><td>Merchant onboarding record with ID {} not found.</td><td>The provided <code>merchant_onboarding_id</code> doesn’t exist in our system.</td><td>Create a new <code>merchant_onboarding_record</code> using the <code>POST /merchant/onboarding</code> API.</td></tr><tr><td><code>POST</code></td><td>2514</td><td>merchant_already_onboarded</td><td>This merchant already exists in Violet (Merchant Id: {}). Once a merchant has been onboarded, you must directly interact with the <a href="/pages/4LBICFd5WAFobRST5Gq0">Merchant endpoints available here</a> to retrieve or update merchant details.</td><td>Call is made after the merchant has already been onboarded through Violet Connect and that merchant in Violet has the same <code>channel_merchant_id</code> as this merchant onboarding update request.</td><td>Directly interact with the Merchant endpoints available in Violet Docs to retrieve/update merchant details.</td></tr></tbody></table>

**Update Limitations**

<table><thead><tr><th width="252.26953125">Field</th><th>Can be updated?</th><th>Behavior if passed in</th><th>Notes</th></tr></thead><tbody><tr><td><code>merchant_onboarding_id</code></td><td>No</td><td>Used for record retrieval</td><td>If a <code>merchant_onboarding_id</code> is passed in and a record is not found, a <code>merchant_onboarding_record_not_found</code> exception will be thrown.</td></tr><tr><td><code>channel_merchant_id</code></td><td>Yes</td><td>Updated</td><td></td></tr><tr><td><code>date_created</code></td><td>No</td><td>Ignored</td><td></td></tr><tr><td><code>date_last_modified</code></td><td>No</td><td>Ignored</td><td></td></tr></tbody></table>

#### Retrieve a specific Merchant Onboarding Record

Returns the Merchant Onboarding Record for the given `merchant_onboarding_id`.

```jsx
GET /v1/merchants/onboard/:merchant_onboarding_id
```

Request Parameters

<table><thead><tr><th width="242.69140625">Field</th><th>Type</th><th width="103.9453125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>merchant_onboarding_id</code></td><td>Path Parameter</td><td>Yes</td><td>The unique identifier for this merchant’s onboarding record. This value was returned as a part of the Create External Account call.</td></tr></tbody></table>

Violet will respond with the following if a merchant onboarding record matching the given id is found.

<details>

<summary>Sample Response</summary>

```json
{
  "merchant_onboarding_id": 10000,
  "app_id": 10385,
  "channel_merchant_id": "chnl_123456789",
  "payout_details": {
    "payment_provider": "STRIPE",
    "payment_provider_metadata": {
      "stripe_account_id": "acct_123456789"
    }
  },
  "date_created": "2024-06-24T15:30:55+0000",
  "date_last_modified": "2024-06-24T15:30:57+0000"
}
```

</details>

**Potential Errors**

<table><thead><tr><th width="89.48046875">Request</th><th width="96.640625">Error Code</th><th width="330.34765625">Error Title</th><th width="214.59765625">Error Message</th><th width="285.73828125">Reason</th><th width="221.140625">How to Fix</th></tr></thead><tbody><tr><td><code>PUT</code></td><td>4429</td><td>merchant_onboarding_record_not_found</td><td>Merchant onboarding record with ID {} not found.</td><td>The provided <code>merchant_onboarding_id</code> doesn’t exist in our system.</td><td>Create a new <code>merchant_onboarding_record</code> using the <code>POST /merchant/onboarding</code> API.</td></tr><tr><td><code>POST</code></td><td>2514</td><td>merchant_already_onboarded</td><td>This merchant already exists in Violet (Merchant Id: {}). Once a merchant has been onboarded, you must directly interact with the <a href="/spaces/8lXIp71Ct5qCUhXjko2q/pages/fGBfj43OVbWWB6k2vV6H">Merchant endpoints available here</a> to retrieve or update merchant details.</td><td>Call is made after the merchant has already been onboarded through Violet Connect and that merchant in Violet has the same <code>channel_merchant_id</code> as this merchant onboarding update request.</td><td>Directly interact with the Merchant endpoints available in Violet Docs to retrieve/update merchant details.</td></tr></tbody></table>

### View all Merchant Onboarding Records

Returns a paginated list of all onboarding records you’ve created.

```jsx
GET /v1/merchants/onboard
```

Request Parameters

| Field  | Type            | Required | Description                                                                                                                                                                                                             |
| ------ | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size` | Query Parameter | No       | Maximum number of items to be returned in the response. By default, 20 elements will be returned. The `total_pages` and `total_elements` in the response will denote the total number of elements available.            |
| `page` | Query Parameter | No       | Maximum number of items to be returned in the response. By default, the first page of data will be returned. The `total_pages` and `total_elements` in the response will denote the total number of elements available. |

Violet will respond with a Page of Merchant Onboarding Records that exist. For this example, let’s assume there 3 accounts currently in the onboarding phase.

<details>

<summary>Sample Response</summary>

```json
{
    "content": [
      {
				"merchant_onboarding_id": 10000,
				"app_id": 10385,
				"channel_merchant_id": "chnl_123456789",
				"payout_details": {
                    "payment_provider": "STRIPE",
                    "payment_provider_metadata": {
                        "stripe_account_id": "acct_123456789"
                    }
                },
				"date_created": "2024-06-24T15:30:55+0000",
				"date_last_modified": "2024-06-24T15:30:57+0000"
			},
			{
				"merchant_onboarding_id": 10001,
				"app_id": 10385,
				"channel_merchant_id": "chnl_1111111111",
				"payout_details": {
                    "payment_provider": "STRIPE",
                    "payment_provider_metadata": {
                        "stripe_account_id": "acct_1111111111"
                    }
                },
				"date_created": "2024-06-24T15:30:55+0000",
				"date_last_modified": "2024-06-24T15:30:57+0000"
			},
			{
				"merchant_onboarding_id": 10003,
				"app_id": 10385,
				"channel_merchant_id": "chnl_222222222",
				"payout_details": {
                    "payment_provider": "STRIPE",
                    "payment_provider_metadata": {
                        "stripe_account_id": "acct_222222222"
                    }
				},
				"date_created": "2024-06-24T15:30:55+0000",
				"date_last_modified": "2024-06-24T15:30:57+0000"
			}
    ],
    "pageable": {
        "page_number": 0,
        "page_size": 3,
        "sort": {
            "unsorted": false,
            "sorted": true,
            "empty": false
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "total_pages": 1,
    "total_elements": 3,
    "last": false,
    "number_of_elements": 3,
    "first": true,
    "size": 3,
    "number": 0,
    "sort": {
        "unsorted": false,
        "sorted": true,
        "empty": false
    },
    "empty": false
}
```

</details>

If no merchants are in the onboarding state, a page with empty content will be returned.

### During Violet Connect

If you've sent Violet onboarding data ahead of time—such as merchant identifiers or payout credentials—you’ll need to ensure that data is correctly matched when the merchant begins the Violet Connect process.

#### Violet Connect

Each channel has a custom Violet Connect URL to onboard merchants. To associate an in-progress onboarding record with a merchant during Connect, include either the `channel_merchant_id` or the `merchant_onboarding_id` as a query parameter in the Connect link.

To onboard a merchant, each channel has a custom Violet Connect link. To learn about Violet Connect in more detail, refer to our [documentation](/prism/violet-connect.md).

For example, the Violet Connect URL could be:

`https://connect.violet.io/<channel_custom_url>/login?channel_merchant_id=chnl_123456789`

or it could be

`https://connect.violet.io/<channel_custom_url>/login?merchant_onboarding_id=10002`

When the merchant completes Violet Connect, Violet will automatically link the onboarding record to the new Merchant. After this point, the onboarding record is removed, and further updates must be made via the [Merchant APIs](/api-reference/merchants/merchant/get-merchants.md).

#### Merchant Webhooks

Upon successful onboarding, Violet emits the following webhook events:

* `MERCHANT_CONNECTED` – Sent when the merchant completes Violet Connect

Scenario Specific:

* `MERCHANT_PAYOUT_ACCOUNT_CREATED` – Sent if payout details were provided during onboarding and a payout account was successfully created

Learn more about these events and their payloads in our [Merchant Webhooks](/prism/webhooks.md#merchants) and [Payment Webhooks](https://github.com/violetio/docs/blob/main/channel-docs/prism/violet-connect/guides/broken-reference/README.md) documentation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/prism/violet-connect/guides/pre-provisioning-merchant-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.