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

## Endpoint

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

### Path Parameters

<ParamField path="id" type="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
</ParamField>

## Prerequisites

<Card>
  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
</Card>

## Example Request

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

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

<Steps>
  <Step title="created → executing">
    Initial transition when execution begins
  </Step>

  <Step title="executing → completed">
    All transfers processed successfully
  </Step>

  <Step title="executing → partially_completed">
    Some transfers succeeded, some failed
  </Step>

  <Step title="executing → failed">
    All transfers failed to process
  </Step>
</Steps>

## Webhook Events

Monitor these webhook events for bulk transfer status:

<AccordionGroup>
  <Accordion title="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
      }
    }
    ```
  </Accordion>

  <Accordion title="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
      }
    }
    ```
  </Accordion>

  <Accordion title="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"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

<ResponseField name="invalid_status" type="error">
  Bulk transfer is not in executable state

  * Status code: 400
  * Must be in `created` status
</ResponseField>

<ResponseField name="insufficient_balance" type="error">
  Insufficient balance for transfers

  * Status code: 400
  * Check available balance
</ResponseField>

<ResponseField name="bulk_transfer_expired" type="error">
  Bulk transfer has expired

  * Status code: 400
  * Create new bulk transfer
</ResponseField>

<ResponseField name="validation_error" type="error">
  One or more transfers invalid

  * Status code: 422
  * Fix validation issues first
</ResponseField>

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

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

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

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