​
Overview

The Cancel Bulk Transfer endpoint allows you to stop a pending bulk transfer from being processed. You can cancel the entire batch or specific transfers within it, depending on their current status.

Only bulk transfers in created or executing status can be cancelled. Completed, expired, or already cancelled transfers cannot be modified.

​
Endpoint

POST /bulk-transfers/{id}/cancel

​
Path Parameters

​
id
string
required

The unique identifier of the bulk transfer to cancel

​
Request Example

curl -X POST "https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/cancel" \
-H "Authorization:  YOUR_API_KEY"

​
Response Examples

{
  "data": {
    "created_at": "2024-10-02T17:39:26.049258",
    "description": "Monthly Vendor Payments",
    "expires_at": "2024-10-03T17:39:25Z",
    "failed_transfer_count": 0,
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "items": [],
    "metadata": {},
    "owner": {
      "id": "65fb1bf9-10e7-4556-8005-0c3249b8df36",
      "type": "personal"
    },
    "reference": "46f3ef38-22de-4498-a6d3-13749aa2a0a7",
    "status": "cancelled",
    "successful_transfer_count": 0,
    "total_transfer_count": 0,
    "updated_at": "2024-10-02T17:39:26Z"
  }
}

​
Status Transitions

When you cancel a bulk transfer:

  1. Status changes from created/executing to cancelled

  2. All pending transfers are marked as cancelled

  3. In-progress transfers complete normally

  4. Completed transfers remain unchanged

​
Webhook Events

Monitor these events for cancellation status:

​
Error Handling

​
bulk_transfer_not_found
error

The specified bulk transfer doesn’t exist

  • Verify the bulk transfer ID

  • Check the ID format

​
invalid_state
error

Transfer cannot be cancelled in current state

  • Only created/executing transfers can be cancelled

  • Check current transfer status

​
partial_cancellation
error

Some transfers could not be cancelled

  • In-progress transfers will complete

  • Check individual transfer statuses

​
Refund Handling

For transfers that require refunds:

  1. Successfully cancelled transfers are automatically reversed

  2. Funds are returned to your balance

  3. Refund status is tracked via webhooks

  4. Processing time varies by payment method

Some payment methods may have specific refund restrictions or processing times.

​
Best Practices

  1. Pre-cancellation Checks

    • Verify bulk transfer status

    • Check for in-progress transfers

    • Consider timing of cancellation

  2. Monitoring

    • Implement webhook handling

    • Track cancellation status

    • Monitor refund processing

  3. Error Handling

    • Handle partial cancellations

    • Implement retry logic

    • Log cancellation attempts

Need Help?

For additional assistance: