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

# Update Bulk Transfer

> Add or modify transfers within an existing bulk transfer batch

## Overview

The Update Bulk Transfer endpoint allows you to add transfers to an existing bulk transfer batch. Use this endpoint to populate your bulk transfer with individual payment instructions before execution.

> [!NOTE]
>
> Before adding transfers:
>
> * Ensure the bulk transfer is in `created` status
> * Verify the batch hasn't expired
> * Check that you haven't exceeded maximum transfer limits

## Endpoint

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

## Request Parameters

**id** `string` *required*

The unique identifier of the bulk transfer to update

**items** `array` *required*

Array of transfer items to add to the batch

**Transfer Item Fields**

**amount** `number` *required*

Transfer amount in smallest currency unit (e.g., cents)

**beneficiary** `object` *required*

Beneficiary payment details

**Beneficiary Fields**

**account\_name** `string` *required*

Name on the beneficiary account

**account\_number** `string` *required*

Account number for the beneficiary

**bank\_code** `string` *required*

Bank identifier code

**bank\_name** `string`

Name of the beneficiary bank

**routing\_number** `string`

Bank routing number (required for US transfers)

**type** `string` *required*

Type of beneficiary account (e.g., "bank\_account")

**currency** `string` *required*

Three-letter currency code

**save\_beneficiary** `boolean`

Whether to save beneficiary for future use

**source\_currency** `string` *required*

Currency code for the source amount

**destination\_currency** `string` *required*

Currency code for the destination amount

**reference** `string` *required*

Unique reference for this transfer

**reason** `string`

Description or reason for the transfer

## Example Request

```bash cURL theme={null}
curl -X POST "https://api.spendjuice.com/bulk-transfers/88dbcb86-5025-4ac9-9750-4aa5a77a723c/transfers" \
-H "Authorization:  YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "items": [
    {
      "amount": 100000,
      "beneficiary": {
        "account_name": "Rodrigo Kerluke",
        "account_number": "1111111111",
        "bank_code": "101",
        "bank_name": "McKenzie Bank",
        "routing_number": "111000038",
        "type": "bank_account",
        "currency": "USD",
        "save_beneficiary": true
      },
      "destination_currency": "USD",
      "source_currency": "USD",
      "reference": "transfer-ref-001",
      "reason": "Monthly salary payment"
    }
  ]
}'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.spendjuice.com/bulk-transfers/88dbcb86-5025-4ac9-9750-4aa5a77a723c/transfers',
  {
    method: 'POST',
    headers: {
      'Authorization': ' YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      items: [
        {
          amount: 100000,
          beneficiary: {
            account_name: "Rodrigo Kerluke",
            account_number: "1111111111",
            bank_code: "101",
            bank_name: "McKenzie Bank",
            routing_number: "111000038",
            type: "bank_account",
            currency: "USD",
            save_beneficiary: true
          },
          destination_currency: "USD",
          source_currency: "USD",
          reference: "transfer-ref-001",
          reason: "Monthly salary payment"
        }
      ]
    })
  }
);
```

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

response = requests.post(
    'https://api.spendjuice.com/bulk-transfers/88dbcb86-5025-4ac9-9750-4aa5a77a723c/transfers',
    headers={
        'Authorization': ' YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'items': [{
            'amount': 100000,
            'beneficiary': {
                'account_name': 'Rodrigo Kerluke',
                'account_number': '1111111111',
                'bank_code': '101',
                'bank_name': 'McKenzie Bank',
                'routing_number': '111000038',
                'type': 'bank_account',
                'currency': 'USD',
                'save_beneficiary': True
            },
            'destination_currency': 'USD',
            'source_currency': 'USD',
            'reference': 'transfer-ref-001',
            'reason': 'Monthly salary payment'
        }]
    }
)
```

## Response Format

**data** `array`

Array of created transfer items

**Transfer Response Fields**

**id** `string`

Unique identifier for the transfer

**batch\_id** `string`

ID of the parent bulk transfer

**status** `string`

Current status of the transfer:

* created - Initial state
* processing - Transfer in progress
* completed - Successfully processed
* failed - Processing failed

**created\_at** `string`

Creation timestamp (ISO 8601)

**updated\_at** `string`

Last update timestamp (ISO 8601)

**source\_amount** `object`

Amount and currency of the transfer

**destination\_amount** `object`

Converted amount and currency (if applicable)

**rate** `number`

Exchange rate used (if applicable)

## Validation Rules

> **Transfer Limits**
>
> * Maximum 100 transfers per batch
> * Minimum amount: \$1 equivalent
> * Maximum amount: Based on account tier

> **Reference Rules**
>
> * Must be unique within the batch
> * Maximum length: 64 characters
> * Alphanumeric characters, hyphens, and underscores only

> **Currency Rules**
>
> * Must be valid ISO currency codes
> * Source currency must match account currency
> * Currency conversion fees may apply

## Error Handling

**invalid\_status** `error`

Bulk transfer is not in editable state

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

**batch\_full** `error`

Maximum number of transfers reached

* Status code: 400
* Remove existing transfers first

**validation\_error** `error`

Invalid transfer parameters

* Status code: 422
* Check error details for specific fields

## Best Practices

1. **Batch Organization**
   * Group similar transfers together
   * Use consistent currencies when possible
   * Include clear references and descriptions
   * Validate beneficiary details before adding

2. **Error Management**
   * Implement proper error handling
   * Validate transfers before submission
   * Keep track of failed additions
   * Retry failed transfers with corrected data

3. **Performance**
   * Add transfers in reasonable batch sizes
   * Monitor rate limits
   * Handle timeouts appropriately
   * Log all operations

> **Next Steps**
>
> After adding transfers:
>
> * [Review the bulk transfer](/transfers/bulk-transfers/get-bulk-transfer-details.md)
> * [Execute the transfers](/transfers/bulk-transfers/execute-bulk-transfer.md)
> * Monitor progress via webhooks


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