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

## Endpoint

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

## Path Parameters

**id** `string` *required*

The unique identifier of the bulk transfer to cancel

## Request Example

```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'}
)
```

## Response Examples

```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"
  }
}
```

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

> **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
>   }
> }
> ```

> **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"
>   }
> }
> ```

## Error Handling

**bulk\_transfer\_not\_found** `error`

The specified bulk transfer doesn't exist

* Verify the bulk transfer ID
* Check the ID format

**invalid\_state** `error`

Transfer cannot be cancelled in current state

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

**partial\_cancellation** `error`

Some transfers could not be cancelled

* In-progress transfers will complete
* Check individual transfer statuses

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

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

> **Need Help?**
>
> For additional assistance:
>
> * Review [Error Handling Guide](https://docs.juicyway.com/errors.md)
> * Contact [Support](mailto:support@juicyway.com)
> * Check [Webhook Documentation](https://docs.juicyway.com/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.