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

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

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"

​
Response Format

​
Success Response (202 Accepted)

{
  "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:

​
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

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: