Disable automatic payouts

Switch from automatic to manual payout mode for explicit control over settlement timing. This guide walks you through disabling automatic payouts, triggering manual payouts, and re-enabling automatic mode when ready.

For complete details on automatic vs. manual payout modes, see Payouts product documentation.

When to use manual mode

Disable automatic payouts when you need explicit control over settlement timing:

Financial audits and month-end close — Freeze disbursements during reconciliation
Coordinating with business cycles — Align payouts with vendor payments or payroll runs
Testing payout flows — Validate new destinations before trusting them with automatic settlements
Temporary cashflow optimization — Keep funds in your balance temporarily
Managing multi-currency complexity — Stagger payouts strategically by currency

See the Payouts product documentation for detailed explanations of when to use each mode.

Before you disable

Consider these factors:

Your cashflow needs

Automatic payouts provide predictable liquidity. Manual mode requires active management—if you forget to trigger payouts, funds accumulate in your balance.

Check existing payouts

Check payout settings

POST

/payouts/settings

curl https://api.zebo.dev/payouts/settings \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "settings": {
    "schedule": {
      "name": "weekly",
      "type": "automatic",
      "interval": "weekly",
      "schedule_on": "sunday",
      "description": "Automatic weekly payout. Default."
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}

If schedule.type is already manual, you're already in manual mode.

Disable automatic payouts

Switching to manual mode is a single API call—no parameters needed beyond authentication:

Disable automatic payouts

POST

/payouts/disable

curl https://api.zebo.dev/payouts/disable \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "settings": {
    "schedule": {
      "id": "payout_sched_manual",
      "name": "manual",
      "type": "manual",
      "interval": "manual",
      "schedule_on": "manual",
      "spec": {
        "id": "payout_spec_manual",
        "t_plus": "7",
        "label": "7 days",
        "abide": "strict"
      },
      "description": "Manual payout"
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}

What changed

Your payout schedule switched from automatic to manual:

schedule.type: automatic → manual
schedule.name: weekly → manual
schedule.interval: No automatic cadence
destinations: Unchanged

Commerce won't create new automatic payouts. Trigger payouts manually with /payouts/schedule. Balance transactions must still age 7 days before they're eligible.

Trigger manual payouts

With automatic payouts disabled, you control when funds move from your balance to your financial accounts. Use the /payouts/schedule endpoint to trigger payouts on-demand:

Schedule a manual payout

POST

/payouts/schedule

curl https://api.zebo.dev/payouts/schedule \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "reference": "MANUAL-PAYOUT-2025-04-15",
    "max_amount": 500000
  }'

Response

{
  "payout": {
    "id": "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB",
    "destination_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "reference": "MANUAL-PAYOUT-2025-04-15",
    "status": "scheduled",
    "max_amount": { "currency": "ghs", "value": 500000 },
    "amount": null,
    "execute_after": "2025-04-15T14:32:10.000Z",
    "scheduled_at": "2025-04-15T14:32:10.000Z",
    "initiated_at": "2025-04-15T14:32:10.000Z"
  }
}

Key parameters

destination_id: Which financial account receives the funds. Must be one of your configured destinations. Get this from /payouts/settings or list your financial accounts.
reference: Your internal identifier for reconciliation—use payout batch numbers, date stamps, or whatever helps you track disbursements in your systems. Must be unique.
max_amount: Maximum amount you authorize for this payout, in the smallest currency unit (pesewas for GHS, cents for USD). The actual payout may be less if you have fewer eligible balance transactions, but will never exceed this limit.
execute_after (optional): When to start processing the payout. Defaults to "now" if omitted. Use this to schedule future manual payouts: "2025-04-20T09:00:00Z" for a specific time.

Monitoring payout status

Once scheduled, use /payouts/lookup to track execution:

Check payout status

POST

/payouts/lookup

curl https://api.zebo.dev/payouts/lookup \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_id": "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB"
  }'

Payout states: initialized → scheduled → executing → succeeded or failed.

See Schedule a payout for complete parameter reference.

Re-enable automatic payouts

When you're ready to resume automatic settlements, call the /payouts/enable endpoint to switch back to automatic mode:

Enable automatic payouts

POST

/payouts/enable

curl https://api.zebo.dev/payouts/enable \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "settings": {
    "schedule": {
      "name": "weekly",
      "type": "automatic",
      "interval": "weekly",
      "schedule_on": "sunday",
      "description": "Automatic weekly payout. Default."
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}

Once automatic payouts are re-enabled, Commerce will resume creating scheduled payouts on the default weekly cadence. Any manual payouts you triggered while in manual mode complete normally—re-enabling automatic mode doesn't affect in-flight transfers.

Destinations remain unchanged. See Enable automatic payouts for re-enabling details.

Common scenarios

Month-end freeze: Disable on the 28th, reconcile through the 30th, trigger manual payout on the 1st, re-enable automatic mode.

Testing new accounts: Disable automatic mode, configure new destination, test with small manual payout, re-enable once verified.

Vendor payment coordination: Stay in manual mode, trigger payouts aligned with your payment schedule (e.g., Thursday for Friday vendor payments).

Best practices

Document your schedule — Create calendar events or automation for triggering payouts
Use descriptive references — Format: MANUAL-PAYOUT-2025-04-15, not payout1
Monitor aging eligibility — Only transactions aged 7+ days are eligible for payout
Set up balance alerts — Get notified when balance exceeds threshold
Test first — Validate manual payout workflow in test mode before production

Troubleshooting

No eligible transactions: Only balance transactions aged 7+ days are eligible. Check /balance_transactions/page.

Destination not configured: Use /payouts/set_destinations or specify destination_id in /payouts/schedule.

Payout fails immediately: Check latest_error in /payouts/lookup for specific failure reason (account closed, insufficient funds, provider error).

Automatic payouts still running: Existing payouts complete normally. New automatic payouts won't be created.

How to re-enable: Call /payouts/enable or see Enable automatic payouts.

Next steps

Now that you understand manual payout mode, explore related payout concepts:

Enable automatic payouts when you're ready to resume scheduled settlements
Schedule manual payouts for complete parameter reference and examples
Monitor balance transactions to understand what's eligible for payout
Manage payout destinations to configure where funds land
Understand payout schedules to learn about weekly vs. daily cadences

Questions? Check the Payouts API reference for complete endpoint documentation, or contact support at support@zebo.dev.