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

# Execute Bulk Transfer

> Execute a prepared bulk transfer by triggering the payment process for all included transfers

## Overview

The Execute Bulk Transfer endpoint initiates the processing of all transfers within a prepared bulk transfer batch. This operation transitions the bulk transfer from `created` status to `executing` and begins processing individual transfers.

> [!NOTE]
>
> Before executing a bulk transfer:
>
> 1. Ensure all transfer details are correct
> 2. Verify sufficient balance for all transfers
> 3. Check that the bulk transfer hasn't expired
> 4. Confirm no validation errors in transfer items

## Endpoint

```http theme={null}
POST /bulk-transfers/{id}/execute
```

### Path Parameters

**id** `string` *required*

The unique identifier of the bulk transfer to execute

* Must be in `created` status
* Must not be expired
* Must have at least one valid transfer

## Prerequisites

> Before execution can begin:
>
> * All transfers must have valid beneficiary details
> * Total transfer amount must not exceed your limits
> * Your account must have sufficient balance
> * The bulk transfer must not be expired
> * No pending validation issues

## Example Request

```bash cURL theme={null}
curl -X POST "https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/execute" \
-H "Authorization:  YOUR_API_KEY" \
-H "Content-Type: application/json"
```

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

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

response = requests.post(
    'https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/execute',
    headers={
        'Authorization': ' YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
)
```

## Response Format

### Success Response (202 Accepted)

```json theme={null}
{
  "data": {
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "status": "executing",
    "total_transfer_count": 10,
    "successful_transfer_count": 0,
    "failed_transfer_count": 0,
    "created_at": "2024-03-15T10:30:00Z",
    "updated_at": "2024-03-15T10:35:00Z",
    "execution_started_at": "2024-03-15T10:35:00Z"
  }
}
```

## Status Transitions

When a bulk transfer is executed, it goes through these status changes:

**1. created → executing**

Initial transition when execution begins

**2. executing → completed**

All transfers processed successfully

**3. executing → partially\_completed**

Some transfers succeeded, some failed

**4. executing → failed**

All transfers failed to process

## Webhook Events

Monitor these webhook events for bulk transfer status:

> **bulk\_transfer.executing**
>
> Triggered when execution begins
>
> ```json theme={null}
> {
>   "event": "bulk_transfer.executing",
>   "data": {
>     "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
>     "status": "executing",
>     "total_transfer_count": 10
>   }
> }
> ```

> **bulk\_transfer.completed**
>
> Triggered when all transfers complete successfully
>
> ```json theme={null}
> {
>   "event": "bulk_transfer.completed",
>   "data": {
>     "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
>     "status": "completed",
>     "successful_transfer_count": 10,
>     "failed_transfer_count": 0
>   }
> }
> ```

> **bulk\_transfer.failed**
>
> Triggered if execution fails
>
> ```json theme={null}
> {
>   "event": "bulk_transfer.failed",
>   "data": {
>     "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
>     "status": "failed",
>     "error": {
>       "code": "insufficient_balance",
>       "message": "Insufficient balance for transfer"
>     }
>   }
> }
> ```

## Error Handling

**invalid\_status** `error`

Bulk transfer is not in executable state

* Status code: 400
* Must be in `created` status

**insufficient\_balance** `error`

Insufficient balance for transfers

* Status code: 400
* Check available balance

**bulk\_transfer\_expired** `error`

Bulk transfer has expired

* Status code: 400
* Create new bulk transfer

**validation\_error** `error`

One or more transfers invalid

* Status code: 422
* Fix validation issues first

## Rate Limits

> [!NOTE]
>
> Bulk transfer execution is subject to these limits:
>
> * Maximum 1 execution request per bulk transfer
> * Maximum 100 transfers per bulk transfer
> * Maximum 10 concurrent executing bulk transfers

## Best Practices

1. **Pre-execution Validation**
   * Verify all beneficiary details
   * Check sufficient balance
   * Validate transfer amounts
   * Monitor expiration time
2. **Error Handling**
   * Implement webhook handling
   * Monitor individual transfer status
   * Handle partial completions
   * Log execution attempts
3. **Monitoring**
   * Track execution progress
   * Monitor success rates
   * Set up alerts for failures
   * Review execution logs

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


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