---
title: "Simulate merchant advancement"
method: POST
path: "/v1/marketplaces/{marketplaceId}/merchants/{merchantId}/advancements"
tags: ["Merchant advancement"]
---

# Simulate merchant advancement

`POST /v1/marketplaces/{marketplaceId}/merchants/{merchantId}/advancements`

## Request

- Base URL: `https://sandbox.pismolabs.io/merchants`
- URL: `https://sandbox.pismolabs.io/merchants/v1/marketplaces/{marketplaceId}/merchants/{merchantId}/advancements`
- Auth: none declared. Required headers: `Authorization`

Create or simulate a merchant advancement request.  To trigger a simulated advancement request, you must include `confirmAdvancement=false` in the query. If you specify `true`, the advancement request becomes an actual request, not a simulation.<br>

The endpoint enables a merchant to simulate an advancement scenario in order to validate whether or not there is enough balance in the account, as well as how much tax is anticipated. Since a simulated advancement is not a real advancement, it is not processed.

A merchant advancement is sometimes called a prepayment of receivables. You arrange to have a financial institution make regular deposits into your account equal to what you expect to receive in the future from credit card sales in installments or post-dated
checks and bills. The financial institution deducts its fee before it puts the money in your account. You pay back each deposit when you receive
payment from your customers. This is a way of covering business expenses in the short term. It's a cheaper alternative to a loan.<br>

<b>Note</b>:
- If the merchant is the head merchant (also called a centralizer), the advanced amount is given to the head merchant instead of individual branch merchants, this is designed for better manageability.
- If the commercial establishment is not registered as a headquarter or a branch in the current marketplace, the advancement is for a single commercial establishment.
- The merchant must have sufficient balance in the account for the specified date range of the advancement.

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

## Path parameters

- `marketplaceId` integer, required: Marketplace ID
- `merchantId` integer, required: Merchant ID

## Query parameters

- `confirmAdvancement` boolean: When set to `true`, it means you are sending an actual advancement request (confirmed advancement); otherwise, it is a simulated advancement. The default value is `false`.

## Headers

- `Authorization` string, required: Authorization token

## Request body

- MerchantsAdvancementsRequest
  - `begin_date` string, date, required: Used for searching merchant advancement requests. This is the start date of your search range.
  - `request_date` string, date, required: Date for payment of the advancement (YYYY-MM-DD). Must be greater than or equal to today, where "today" is evaluated in the merchant program's resolved timezone. The organization's timezone is used as fallback.
  - `amount` number, float, required: Net amount to be paid in advance
  - `currency_code` string: Represents the currency with an ISO-4217 alphabetic or numeric (3 characters) string. For example, you represent Brazilian real with either BRL or 986. If you don't provide this code, the system uses the currency from the merchant program.
  - `real_time_settlement` boolean, required: If `true`, the transaction is settled real-time; that is, at the exact moment. Default is `false`
  - `end_date` string, date: Used for searching merchant advancement requests. This is the end date of your search range
  - `campaign_advancement_fee` number, float: Campaign advancement fee to be applied to the current advancement request. It replaces the advancement fee set for the merchant in the request
  - `campaign_discount_rate` number, float: Campaign discount rate to be applied to all merchants in the current advancement request
  - `merchants` object[]
    - `merchant_id` integer: Merchant ID of the advancement request. Must be the current merchant or a branch of the current merchant
    - `campaign_discount_rate` number, float: Rate to be applied to a single merchant

## Response `200`

OK

- MerchantsAdvancementsResponse
  - `simulation_id` string: A unique UUID generated for the simulated advancement. This field is only returned if it is a simulation
  - `advancement_request_id` integer: This field is returned only if it's an actual advancement request (`EFFECTIVE`)
  - `type` string: Operation type, returns either `SIMULATION` or `EFFECTIVE`
  - `currency_code` string: ISO-4217 alphabetic (3 characters) currency code.
  - `begin_date` string, date: Used for searching merchant transactions. This is the start date of your search range
  - `end_date` string, date: Used for searching merchant transactions. This is the end date of your search range
  - `request_date` string, date: Advancement request date

## Other responses

- `400`: BAD REQUEST
- `404`: Marketplace or merchant does not belong to the tenant

---

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