> ## 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.

# Cancel Charges by Period

> Request the cancellation of a merchant Payins created within a period

# Cancel Charges by Period

Request the asynchronous cancellation of every eligible Payin created by a merchant within a
date range, filtered by payment method. Useful when a merchant needs all of its open charges
canceled at once (e.g. when the account is being deactivated).

<Note>
  This is an **asynchronous** request. The response returns the **estimated** number of charges
  that matched the filters and were queued for cancellation. The actual cancellation is performed
  by background jobs.
</Note>

## Eligibility

<Warning>
  **Cancellation Restrictions** — a charge is only queued for cancellation when it:

  * has `status = created`
  * was created between `start_date` and `end_date`
  * matches one of the requested `payment_method` values
  * respects the minimum time since creation (see below)
</Warning>

## Minimum Time Before Cancellation

* **pix**: at least 5 minutes after creation
* **billet**: at least 30 minutes after creation

## Request Body

<ParamField body="merchant_id" type="integer" required>
  The ID of the merchant whose charges will be canceled. Must belong to the authenticated user.
</ParamField>

<ParamField body="start_date" type="string" required>
  Start of the creation period, format `Y-m-d H:i:s`.

  Example: `2025-09-30 00:00:00`
</ParamField>

<ParamField body="end_date" type="string" required>
  End of the creation period, format `Y-m-d H:i:s`. Must be after `start_date`.

  Example: `2025-12-31 00:00:00`
</ParamField>

<ParamField body="payment_method" type="array" required>
  The payment methods to include in the cancellation. Must contain at least one value.

  Useful values:

  * `pix`
  * `billet`

  <Warning>
    The value `credit-card` is accepted by validation but credit-card charges are **never**
    eligible for cancellation, so including it has no effect.
  </Warning>
</ParamField>

## Response

<ResponseField name="status" type="boolean">
  Indicates if the cancellation request was successfully accepted.
</ResponseField>

<ResponseField name="data" type="object">
  Response data object.

  <Expandable title="Data">
    <ResponseField name="estimated_total" type="integer">
      The estimated number of charges that matched the filters and were queued for cancellation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message about the cancellation request.
</ResponseField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.sandbox.wepayout.com.br/v2/payin/payments/request-cancel-by-period \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123' \
    --header 'Content-Type: application/json' \
    --data '{
      "merchant_id": 123,
      "start_date": "2025-09-30 00:00:00",
      "end_date": "2025-12-31 00:00:00",
      "payment_method": ["pix", "billet"]
    }'
  ```

  ```javascript JavaScript theme={null}
  async function cancelChargesByPeriod(payload) {
    const response = await fetch(
      'https://api.sandbox.wepayout.com.br/v2/payin/payments/request-cancel-by-period',
      {
        method: 'DELETE',
        headers: {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
      }
    );

    return await response.json();
  }

  // Usage
  const result = await cancelChargesByPeriod({
    merchant_id: 123,
    start_date: '2025-09-30 00:00:00',
    end_date: '2025-12-31 00:00:00',
    payment_method: ['pix', 'billet']
  });
  console.log('Cancellation result:', result);
  ```

  ```python Python theme={null}
  import requests

  def cancel_charges_by_period(payload):
      url = 'https://api.sandbox.wepayout.com.br/v2/payin/payments/request-cancel-by-period'
      headers = {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123',
          'Content-Type': 'application/json'
      }

      response = requests.delete(url, headers=headers, json=payload)
      return response.json()

  # Usage
  result = cancel_charges_by_period({
      'merchant_id': 123,
      'start_date': '2025-09-30 00:00:00',
      'end_date': '2025-12-31 00:00:00',
      'payment_method': ['pix', 'billet']
  })
  print('Cancellation result:', result)
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "status": true,
    "data": {
      "estimated_total": 42
    },
    "message": "Cancellation requested successfully"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "status": false,
    "message": "It is not possible to cancel payins with the applied filters."
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "end_date": [
        "The end date must be a date after start date."
      ]
    }
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  **Pix Cancellation**: Pix charges are canceled instantly once the job runs.
</Note>

<Warning>
  **Billet Cancellation**: Billet charges require at least 1 day to move from `drop_requested` to `canceled`, as the process depends on confirmation from the payment processor.
</Warning>

<Tip>
  To cancel a specific set of charges instead of a whole period, use [Cancel Charges](/api-reference/cash-in/payin/request-multiple-cancel) with a list of IDs.
</Tip>