> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Submerchant Markup

> Create or replace the markup configuration of a submerchant.

# Configure Submerchant Markup

Use this endpoint to set a submerchant's own markup for each product and payment method. The submerchant's markup takes priority over the merchant's global markup, but not over an inline `markup` sent in the request.

<Warning>
  **This endpoint replaces the whole configuration.** Every call removes the submerchant's current markups and saves only the items in `markups`. Any product and payment method you leave out goes back to the global markup.
</Warning>

## Path Parameters

<ParamField path="merchantId" type="integer" required>
  ID of the merchant (parent account). It must be one of the authenticated user's companies.
</ParamField>

<ParamField path="subMerchantId" type="integer" required>
  ID of the submerchant. It must be a submerchant of `merchantId`.
</ParamField>

## Request Body

<ParamField body="markups" type="array[object]" required>
  Markup configurations for the submerchant. Send between `1` and `8` items, and at most one item for each `product` and `payment_method` pair.

  <Expandable title="Markup Object">
    <ParamField body="product" type="string" required>
      Product where the markup will be applied.

      Allowed values: `payin`, `payout`
    </ParamField>

    <ParamField body="payment_method" type="string" required>
      Payment method where the markup will be applied.

      Allowed values:

      * For `payin`: `pix`, `billet`, `credit_card`
      * For `payout`: `pix`, `ted`
    </ParamField>

    <ParamField body="mode" type="string" required>
      Type of markup to be applied.

      Allowed values:

      * `fixed`: fixed amount (BRL) per transaction
      * `percent`: percentage over the transaction amount
    </ParamField>

    <ParamField body="amount" type="number" required>
      Markup value. In BRL when `mode` is `fixed`, and a percentage when `mode` is `percent` (`1.5` means 1.5%).

      Must be greater than or equal to `0.01`.
    </ParamField>

    <ParamField body="min_charge_value" type="number">
      Minimum markup amount (BRL) when `mode` is `percent`.

      Business rules:

      * **Required** when `mode` = `percent`
      * **Prohibited** when `mode` = `fixed`
      * Must be greater than or equal to `0.01`
    </ParamField>

    <ParamField body="max_charge_value" type="number">
      Maximum markup amount (BRL) when `mode` is `percent`.

      Business rules:

      * **Required** when `mode` = `percent`
      * **Prohibited** when `mode` = `fixed`
      * Must be greater than or equal to `min_charge_value`
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  Unlike the global markup, a submerchant markup with `mode` = `percent` requires **both** `min_charge_value` and `max_charge_value`.
</Note>

## Request Examples

<CodeGroup>
  ```json Payin and payout markup theme={null}
  {
    "markups": [
      {
        "product": "payin",
        "payment_method": "pix",
        "mode": "percent",
        "amount": 1.4,
        "min_charge_value": 1.0,
        "max_charge_value": 5.0
      },
      {
        "product": "payin",
        "payment_method": "billet",
        "mode": "fixed",
        "amount": 2.0
      },
      {
        "product": "payout",
        "payment_method": "pix",
        "mode": "fixed",
        "amount": 0.8
      }
    ]
  }
  ```

  ```bash cURL theme={null}
  curl -X PUT "https://api.sandbox.wepayout.com.br/v2/account/123/submerchants/1234/markups" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "markups": [
        {
          "product": "payin",
          "payment_method": "pix",
          "mode": "percent",
          "amount": 1.4,
          "min_charge_value": 1.0,
          "max_charge_value": 5.0
        }
      ]
    }'
  ```
</CodeGroup>

## Response

Returns the submerchant with its updated markup, with the same fields as [Get Submerchant Markup](/api-reference/markup/submerchant/get-submerchant-markup).

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": 1234,
    "name": "Store X",
    "legal_name": "Store X LTDA",
    "document": "12345678000190",
    "has_markup": true,
    "payin": [
      {
        "id": 61,
        "payment_method": "pix",
        "mode": "percent",
        "amount": "1.40",
        "min_charge_value": "1.00",
        "max_charge_value": "5.00"
      }
    ],
    "payout": [],
    "updated_at": "2026-09-29 14:02:37"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "markups.0.payment_method": [
        "The payment method ted is not allowed with product payin."
      ],
      "markups.1.min_charge_value": [
        "Minimum and maximum values are required when the mode is percent."
      ],
      "markups.2.min_charge_value": [
        "Minimum and maximum values do not apply to the fixed mode."
      ],
      "markups.3.max_charge_value": [
        "The minimum value cannot be greater than the maximum value."
      ],
      "markups.4.payment_method": [
        "There is more than one configuration for the same product and payment method."
      ]
    }
  }
  ```

  ```json 422 Unprocessable Entity - Not a submerchant of this merchant theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "subMerchantId": [
        "The subaccount 7777 does not belong to this account."
      ]
    }
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Failed to create markup."
  }
  ```
</ResponseExample>

## Related Resources

<CardGroup cols={2}>
  <Card title="Batch Apply Submerchant Markup" icon="layer-group" href="/api-reference/markup/submerchant/batch-apply-submerchant-markup">
    Apply the same markup to many submerchants
  </Card>

  <Card title="Remove Submerchant Markup" icon="trash" href="/api-reference/markup/submerchant/delete-submerchant-markup">
    Go back to the global markup
  </Card>

  <Card title="About Markup" icon="circle-info" href="/markup/about-markup">
    Learn about markup types and configuration levels
  </Card>

  <Card title="Create Merchant Markup" icon="plus" href="/api-reference/markup/account/create-merchant-markup">
    Configure the global markup
  </Card>
</CardGroup>