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

# Create merchant

`POST /v1/merchants`

## Request

- Base URL: `https://sandbox.pismolabs.io/merchants`
- URL: `https://sandbox.pismolabs.io/merchants/v1/merchants`
- Auth: HTTP bearer

Create merchant. You use this endpoint to register a merchant (store) in a marketplace using the information the merchant provides.

<b>Note:</b> Before you create merchants, you must create a Merchant program, using the [Create program based on template](ref:createprogrambasedontemplate) endpoint with `type` set to `MERCHANT`. If a program of type `MERCHANT` is not provided, the request returns an error.
By default, when a merchant is created, the Pismo platform assigns it to the first existing program of type `MERCHANT` in the Org. However, you have the option of specifying a program by providing its ID in the `program_id` field.

<b>Note:</b> When a `x-marketplace-id` header is provided, the merchant is automatically linked to the provided marketplace after creation.

For more information about merchants, refer to the <a href="https://developers.pismo.io/pismo-docs/docs/seller-management-overview" target="blank">Seller management overview</a> guide.<br>

This endpoint generates a [Merchant created](https://developers.pismo.io/events/docs/merchants-merchant-created-1) event.

## Headers

- `Content-Type` string
- `Authorization` string
- `x-marketplace-id` integer

## Request body

- POSTMerchantRequest
  - `document_number` string, required: Merchant document number. This is the government document code, such as a government-issued tax ID.
  - `name` string, required: Merchant name
  - `email` string, required: Email address
  - `brand_name` string: Merchant brand name. Note that this is different from a merchant's legal registered name. For example, <i>Great Company</i> as opposed to <i>Great Company, LLC</i> (legal entity name).
  - `municipal_registration` string: Merchant's municipal registration number
  - `contact` string: Name of contact
  - `zip_code` string: Postal code. This is called a zip code in the United States, but you can use other types of postal codes.
  - `number` integer: Numerical identifier for the specific location within a street or avenue
  - `address` string: Name of the street, avenue, or primary thoroughfare of the address
  - `complementary_address` string: Additional address details that help pinpoint the exact location, such as building, apartment, or floor
  - `neighborhood` string: Name of the neighborhood or administrative region where the address is located
  - `state` string: Abbreviation or full name of the state, province, or administrative division
  - `city` string: Name of the city or municipality
  - `country` string: Full name of the country according to international standards or local registry
  - `area_code` string: Area code. The US, Canada, and certain other countries divide their telephone service into regions, which are identified by numbers called area codes. In the US, for example, area codes are 3-digit numbers.
  - `phone` string: Phone number. Parentheses and dashes are optional.
  - `additional_area_code` string: Additional area code (for `additional_phone`)
  - `additional_phone` string: Number for an additional phone. Parentheses and dashes are optional.
  - `program_id` integer: Program ID for merchant account
  - `external_code` string: Code for merchant category. The category is the type of business. You can use the endpoint <a href="https://developers.pismo.io/pismo-docs/reference/get_v1-businesscategories">Retrieves business categories corresponding to query parameters</a> to get a list of business categories and their external codes.
  - `external_id` string: Internal ID used by client to reference a merchant in their domain.
  - `creditor` POSTMerchantCreditorRequest: This is the entity from which the merchant receives money when a transaction is settled. It should be a Pismo account. You can either provide an `id` to create a merchant with an already existing creditor, or fill in the creditor fields to create a new creditor for the created merchant.
    - `name` string, required: Creditor name
    - `id` integer: Creditor ID
    - `crediting_method` 'ACCOUNT': Crediting method. Must be set to `ACCOUNT`.
    - `advancement_fee` string: Advancement fee for creditor. If you don't specify a value for this field, the server tries to retrieve the value from the <b>Fixed fee applied to the advancement transaction</b> parameter for the provided `program_id` in the Pismo console. If the `program_id` is not provided or the parameter is disabled, the server uses the default value of `10`.
    - `discount_rate` string: Advancement discount rate for creditor. If the client doesn't provide a value for this field, the server tries to retrieve the value from the <b>Percentage rate over the anticipated gross amount</b> parameter for the provided `program_id` in the Pismo console. If the `program_id` of the merchant is not found or the parameter is disabled, the server uses the default value of `0.025`.
    - `maximum_advancement_percentage` string: Maximum advancement percentage for creditor. If the client didn't provide a value for this field, the server tries to retrieve the value from the <b>Max percentage that can be anticipated</b> parameter for the provided `program_id` in the Pismo console. If the `program_id` of the merchant is not found or the parameter is disabled, the server uses the default value of `1`.
  - `city_code` string: Official seven-digit numeric code of the city according to the IBGE (Brazilian Institute of Geography and Statistics) code table. Used only for cities in Brazil; this code is unique per city.

## Response `201`

Created

- POSTMerchantResponse
  - `id` integer: Merchant ID
  - `document_number` string: Merchant document number. This is the government document code, such as a government-issued tax ID.
  - `name` string: Merchant name
  - `brand_name` string: Merchant brand name. Note that this is different from a merchant's legal registered name. For example, <i>Great Company</i> as opposed to <i>Great Company, LLC</i> (legal entity name).
  - `municipal_registration` string: Merchant's municipal registration number
  - `category` string: Code name for merchant category. The category is the type of business.
  - `contact` string: Name of contact
  - `email` string: Email address
  - `zip_code` string: Postal code. This is called a zip code in the United States, but you can use other types of postal codes.
  - `address` string: Name of the street, avenue, or primary thoroughfare of the address
  - `complementary_address` string: Additional address details that help pinpoint the exact location, such as building, apartment, or floor
  - `neighborhood` string: Name of the neighborhood or administrative region where the address is located
  - `state` string: Abbreviation or full name of the state, province, or administrative division
  - `city` string: Name of the city or municipality
  - `country` string: Full name of the country according to international standards or local registry
  - `number` integer: Numerical identifier for the specific location within a street or avenue
  - `area_code` string: Area code. The US, Canada, and certain other countries divide their telephone service into regions, which are identified by numbers called area codes. In the US, for example, area codes are 3-digit numbers.
  - `phone` string: Phone number. Parentheses and dashes are optional.
  - `additional_area_code` string: Additional area code (for `additional_phone`)
  - `additional_phone` string: Number for an additional phone. Parentheses and dashes are optional.
  - `program_id` integer: Program ID for merchant account
  - `external_code` string: Code for merchant category. The category is the type of business. You can use the endpoint <a href="https://developers.pismo.io/pismo-docs/reference/get_v1-businesscategories">Retrieves business categories corresponding to query parameters</a> to get a list of business categories and their external codes.
  - `external_id` string: Internal ID used by client to reference a merchant in their domain.
  - `creditor` MerchantCreditorResponse: Get response from merchant creditor.
    - `id` integer: Creditor ID
    - `name` string: Creditor name
    - `crediting_method` 'ACCOUNT': Crediting method. Must be set to `ACCOUNT`.
    - `account` object: Pismo platform account
      - `id` integer: Pismo account ID
    - `advancement_fee` string: Advancement fee for creditor.
    - `discount_rate` string: Advancement discount rate for creditor.
    - `maximum_advancement_percentage` string: Maximum advancement percentage for creditor.

## Other responses

- `400`: Bad Request
- `401`: Access token is missing or invalid
- `500`: Internal server error

---

[API](https://skmtc.dev/pismo/apis/seller-management-merchants.md) - [All operations](https://skmtc.dev/pismo/apis/seller-management-merchants/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/seller-management-merchants/revisions/f0c2e31fbbc0?raw)