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

## Endpoint

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

## Request Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the bulk transfer to update
</ParamField>

<ParamField body="items" type="array" required>
  Array of transfer items to add to the batch

  <Expandable title="Transfer Item Fields">
    <ResponseField name="amount" type="number" required>
      Transfer amount in smallest currency unit (e.g., cents)
    </ResponseField>

    <ResponseField name="beneficiary" type="object" required>
      Beneficiary payment details

      <Expandable title="Beneficiary Fields">
        <ResponseField name="account_name" type="string" required>
          Name on the beneficiary account
        </ResponseField>

        <ResponseField name="account_number" type="string" required>
          Account number for the beneficiary
        </ResponseField>

        <ResponseField name="bank_code" type="string" required>
          Bank identifier code
        </ResponseField>

        <ResponseField name="bank_name" type="string">
          Name of the beneficiary bank
        </ResponseField>

        <ResponseField name="routing_number" type="string">
          Bank routing number (required for US transfers)
        </ResponseField>

        <ResponseField name="type" type="string" required>
          Type of beneficiary account (e.g., "bank\_account")
        </ResponseField>

        <ResponseField name="currency" type="string" required>
          Three-letter currency code
        </ResponseField>

        <ResponseField name="save_beneficiary" type="boolean">
          Whether to save beneficiary for future use
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="source_currency" type="string" required>
      Currency code for the source amount
    </ResponseField>

    <ResponseField name="destination_currency" type="string" required>
      Currency code for the destination amount
    </ResponseField>

    <ResponseField name="reference" type="string" required>
      Unique reference for this transfer
    </ResponseField>

    <ResponseField name="reason" type="string">
      Description or reason for the transfer
    </ResponseField>
  </Expandable>
</ParamField>

## Example Request

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

## Response Format

<ResponseField name="data" type="array">
  Array of created transfer items

  <Expandable title="Transfer Response Fields">
    <ResponseField name="id" type="string">
      Unique identifier for the transfer
    </ResponseField>

    <ResponseField name="batch_id" type="string">
      ID of the parent bulk transfer
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the transfer:

      * created - Initial state
      * processing - Transfer in progress
      * completed - Successfully processed
      * failed - Processing failed
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Creation timestamp (ISO 8601)
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Last update timestamp (ISO 8601)
    </ResponseField>

    <ResponseField name="source_amount" type="object">
      Amount and currency of the transfer
    </ResponseField>

    <ResponseField name="destination_amount" type="object">
      Converted amount and currency (if applicable)
    </ResponseField>

    <ResponseField name="rate" type="number">
      Exchange rate used (if applicable)
    </ResponseField>
  </Expandable>
</ResponseField>

## Validation Rules

<AccordionGroup>
  <Accordion title="Transfer Limits">
    * Maximum 100 transfers per batch
    * Minimum amount: \$1 equivalent
    * Maximum amount: Based on account tier
  </Accordion>

  <Accordion title="Reference Rules">
    * Must be unique within the batch
    * Maximum length: 64 characters
    * Alphanumeric characters, hyphens, and underscores only
  </Accordion>

  <Accordion title="Currency Rules">
    * Must be valid ISO currency codes
    * Source currency must match account currency
    * Currency conversion fees may apply
  </Accordion>
</AccordionGroup>

## Error Handling

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

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

<ResponseField name="batch_full" type="error">
  Maximum number of transfers reached

  * Status code: 400
  * Remove existing transfers first
</ResponseField>

<ResponseField name="validation_error" type="error">
  Invalid transfer parameters

  * Status code: 422
  * Check error details for specific fields
</ResponseField>

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

<Card title="Next Steps">
  After adding transfers:

  * [Review the bulk transfer](/transfers/bulk-transfers/get-bulk-transfer-details)
  * [Execute the transfers](/transfers/bulk-transfers/execute-bulk-transfer)
  * Monitor progress via webhooks
</Card>