Transfer funds to a seller

The Transfers API moves funds between your marketplace account and a seller's, without tying the movement to an order or a payment. Use it to pay sellers after fulfilment, after a returns window, or on a weekly payout run.

Sellers are identified by the seller ID you registered with Bolt when you onboarded them, the same value you pass as X-Bolt-Connect-Seller-Id and in seller_splits.

For the full endpoint reference, see Create a transfer and the rest of the Transfers reference.

When to use Transfers

Bolt offers two ways to move money to a seller. They differ in what triggers the movement.

Use seller splits when a seller's share is decided at checkout. Use Transfers when you decide later what a seller is owed.

Before you begin

Three things must be true before a transfer is accepted. All three are checked on every create, and none are self-serve.

Choose a direction

Your marketplace account is always one side of a transfer. The direction field says which way the money moves.

direction is required and has no default. An implied direction on a money movement is a costly thing to get wrong, so the API asks you to say it every time.

Pay a seller

curl -X POST https://api-sandbox.boltapp.com/v3/transfers \
  -H "X-API-Key: $BOLT_API_KEY" \
  -H "X-Publishable-Key: $BOLT_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "payout",
    "seller_id": "seller_4471",
    "amount": { "units": 4000, "currency": "USD" },
    "reference": "payout-2026-10-14-seller4471",
    "transfer_group": "PAYOUT_2026_10_W2",
    "description": "October payout, orders 95 to 112"
  }'

{
  "id": "trf_9f8e7d6c5b",
  "created_at": "2026-10-14T17:32:28Z",
  "updated_at": "2026-10-14T17:32:28Z",
  "status": "pending",
  "direction": "payout",
  "seller_id": "seller_4471",
  "reference": "payout-2026-10-14-seller4471",
  "amount": { "units": 4000, "currency": "USD" },
  "amount_reversed": { "units": 0, "currency": "USD" },
  "reversed": false,
  "description": "October payout, orders 95 to 112",
  "transfer_group": "PAYOUT_2026_10_W2",
  "payout_reference": null,
  "failure_reason": null,
  "reversals": [],
  "metadata": {}
}

const reference = `payout-${payoutRunId}-${sellerId}`

curl -G https://api-sandbox.boltapp.com/v3/transfers \
  -H "X-API-Key: $BOLT_API_KEY" \
  -H "X-Publishable-Key: $BOLT_PUBLISHABLE_KEY" \
  -d reference=payout-2026-10-14-seller4471

{
  "id": "trf_9f8e7d6c5b",
  "status": "failed",
  "direction": "payout",
  "seller_id": "seller_4471",
  "amount": { "units": 4000, "currency": "USD" },
  "payout_reference": "po_20261015_0031",
  "failure_reason": "account_closed"
}

Group a payout run

Set the same transfer_group on every transfer in a run, then retrieve the whole run in one call. transfer_group cannot be changed after creation.

curl -G https://api-sandbox.boltapp.com/v3/transfers \
  -H "X-API-Key: $BOLT_API_KEY" \
  -H "X-Publishable-Key: $BOLT_PUBLISHABLE_KEY" \
  -d transfer_group=PAYOUT_2026_10_W2 \
  -d page_size=100

{
  "transfers": [
    { "id": "trf_9f8e7d6c5b", "status": "paid", "seller_id": "seller_4471" },
    { "id": "trf_1c2d3e4f5a", "status": "pending", "seller_id": "seller_5512" }
  ],
  "pagination": { "page": 1, "page_size": 100, "total_count": 2 }
}

Each entry is a complete transfer object. The response above is shortened for readability.

Create one transfer per seller. There is no batch create endpoint.

Take money back

How you undo a transfer depends on where it is in its lifecycle.

Cancel a transfer that has not been sent

While a transfer is pending, cancel it. This releases the hold on your balance and nothing ever reaches the seller.

curl -X POST https://api-sandbox.boltapp.com/v3/transfers/trf_1c2d3e4f5a/cancel \
  -H "X-API-Key: $BOLT_API_KEY" \
  -H "X-Publishable-Key: $BOLT_PUBLISHABLE_KEY"

Expected result: a 200 with status: "cancelled".

If the transfer has already moved on, you get transfer_not_cancelable and the message names the current status. Once a transfer is paid, reverse it instead.

Reverse a transfer that has been paid

Once a transfer is paid, create a reversal. Omit amount to reverse the full remaining amount, or supply one to reverse part of it. You can reverse in several steps, up to the transfer's unreversed remainder.

curl -X POST https://api-sandbox.boltapp.com/v3/transfers/trf_9f8e7d6c5b/reversals \
  -H "X-API-Key: $BOLT_API_KEY" \
  -H "X-Publishable-Key: $BOLT_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { "units": 1500, "currency": "USD" },
    "reference": "reversal-return-8831",
    "description": "Partial return, 1 of 3 items"
  }'

{
  "id": "trr_4a3b2c1d0e",
  "created_at": "2026-10-20T11:02:44Z",
  "transfer_id": "trf_9f8e7d6c5b",
  "status": "pending",
  "amount": { "units": 1500, "currency": "USD" },
  "reference": "reversal-return-8831",
  "description": "Partial return, 1 of 3 items",
  "payout_reference": null,
  "metadata": {}
}

Expected result: a 200 with the reversal in pending. A reversal is a money movement in its own right: it goes out on a payout and settles like any transfer, so it is not instantaneous.

A transfer in in_transit can be neither cancelled nor reversed. Wait for paid.

Collect from a seller

To bring funds back from a seller outside of a specific transfer, for example to recover an overpayment, create a transfer with direction set to collection.

curl -X POST https://api-sandbox.boltapp.com/v3/transfers \
  -H "X-API-Key: $BOLT_API_KEY" \
  -H "X-Publishable-Key: $BOLT_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "collection",
    "seller_id": "seller_4471",
    "amount": { "units": 2500, "currency": "USD" },
    "reference": "recovery-2026-10-14-seller4471"
  }'

A collection follows the same lifecycle as a payout, in the opposite direction.

Collections need their own permission. Enabling payouts to a seller does not enable collections from that seller.

Handle errors

Validation failures return invalid_input_parameter with a field naming the problem. Branch on .tag and field, not on the message text.

State errors use their own tags.

Retry only 409, 429, and 5xx, with backoff and the original reference. Every 400, 401, 403, 404, and 422 is deterministic: an identical retry fails in exactly the same way.

Next steps