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

# Cancel Bulk Transfer

> Cancel a pending bulk transfer or individual transfers within a batch

## Overview

The Cancel Bulk Transfer endpoint allows you to stop a pending bulk transfer from being processed. You can cancel the entire batch or specific transfers within it, depending on their current status.

<Note>
  Only bulk transfers in `created` or `executing` status can be cancelled. Completed, expired, or already cancelled transfers cannot be modified.
</Note>

## Endpoint

```bash theme={null}
POST /bulk-transfers/{id}/cancel
```

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the bulk transfer to cancel
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/cancel" \
  -H "Authorization:  YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/cancel',
    {
      method: 'POST',
      headers: {
        'Authorization': ' YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.post(
      'https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/cancel',
      headers={'Authorization': ' YOUR_API_KEY'}
  )
  ```
</CodeGroup>

## Response Examples

<CodeGroup>
  ```json 200 Success theme={null}
  {
    "data": {
      "created_at": "2024-10-02T17:39:26.049258",
      "description": "Monthly Vendor Payments",
      "expires_at": "2024-10-03T17:39:25Z",
      "failed_transfer_count": 0,
      "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
      "items": [],
      "metadata": {},
      "owner": {
        "id": "65fb1bf9-10e7-4556-8005-0c3249b8df36",
        "type": "personal"
      },
      "reference": "46f3ef38-22de-4498-a6d3-13749aa2a0a7",
      "status": "cancelled",
      "successful_transfer_count": 0,
      "total_transfer_count": 0,
      "updated_at": "2024-10-02T17:39:26Z"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": {
      "code": "bulk_transfer_not_found",
      "message": "No bulk transfer found with ID: 7d528558-1c20-4bb6-9a9a-a03c8292b297"
    }
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "error": {
      "code": "invalid_state",
      "message": "Bulk transfer cannot be cancelled in its current state"
    }
  }
  ```
</CodeGroup>

## Status Transitions

When you cancel a bulk transfer:

1. Status changes from `created`/`executing` to `cancelled`
2. All pending transfers are marked as `cancelled`
3. In-progress transfers complete normally
4. Completed transfers remain unchanged

## Webhook Events

Monitor these events for cancellation status:

<AccordionGroup>
  <Accordion title="bulk_transfer.cancelled">
    Fired when the bulk transfer is successfully cancelled

    ```json theme={null}
    {
      "event": "bulk_transfer.cancelled",
      "data": {
        "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
        "status": "cancelled",
        "cancelled_at": "2024-10-02T18:00:00Z",
        "cancelled_transfers": 5,
        "completed_transfers": 2
      }
    }
    ```
  </Accordion>

  <Accordion title="bulk_transfer.transfer.cancelled">
    Fired for each cancelled transfer in the batch

    ```json theme={null}
    {
      "event": "bulk_transfer.transfer.cancelled",
      "data": {
        "bulk_transfer_id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
        "transfer_id": "tr_123abc",
        "status": "cancelled",
        "cancelled_at": "2024-10-02T18:00:00Z"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

<ResponseField name="bulk_transfer_not_found" type="error">
  The specified bulk transfer doesn't exist

  * Verify the bulk transfer ID
  * Check the ID format
</ResponseField>

<ResponseField name="invalid_state" type="error">
  Transfer cannot be cancelled in current state

  * Only created/executing transfers can be cancelled
  * Check current transfer status
</ResponseField>

<ResponseField name="partial_cancellation" type="error">
  Some transfers could not be cancelled

  * In-progress transfers will complete
  * Check individual transfer statuses
</ResponseField>

## Refund Handling

For transfers that require refunds:

1. Successfully cancelled transfers are automatically reversed
2. Funds are returned to your balance
3. Refund status is tracked via webhooks
4. Processing time varies by payment method

<Note>
  Some payment methods may have specific refund restrictions or processing times.
</Note>

## Best Practices

1. **Pre-cancellation Checks**
   * Verify bulk transfer status
   * Check for in-progress transfers
   * Consider timing of cancellation
2. **Monitoring**
   * Implement webhook handling
   * Track cancellation status
   * Monitor refund processing
3. **Error Handling**
   * Handle partial cancellations
   * Implement retry logic
   * Log cancellation attempts

<Card title="Need Help?">
  For additional assistance:

  * Review [Error Handling Guide](/errors)
  * Contact [Support](mailto:support@juicyway.com)
  * Check [Webhook Documentation](/webhooks)
</Card>