Scheduled Transfers

Scheduled transfers give channels granular control over when merchant payouts are executed. Instead of transferring funds immediately after payment capture, you can configure Violet to hold distributions until specific conditions are met—such as order fulfillment—and batch multiple transfers together on a schedule.

Why Use Scheduled Transfers?

The Problem with Immediate Transfers

In a traditional AUTOMATIC transfer setup, funds are transferred to merchants immediately after payment capture. While this provides fast payouts, it creates challenges for certain business models:

• Fulfillment Risk: Merchants receive payment before shipping, increasing exposure if orders are cancelled or not fulfilled

• High Transaction Volume: Each order generates a separate transfer, leading to numerous small transactions

• Chargeback Exposure: Funds are already with the merchant when disputes arise

• Operational Complexity: Difficult to reconcile when transfers happen at unpredictable times

How Scheduled Transfers Help

Scheduled transfers address these challenges by introducing two powerful configuration options:

1. Fulfillment Requirements: Only transfer funds for orders that have been shipped or delivered

2. Batched Transfers: Aggregate multiple orders into a single transfer on a schedule

Configuration Options

Scheduled transfer settings are part of your app's payment configuration. Contact your Violet representative to enable these features.

Scheduled transfer settings can be configured at two levels:

• App Level: Settings apply to all merchants connected to your app by default

• Merchant Level: Override app-level settings for specific merchants who require different transfer schedules

This flexibility allows you to set sensible defaults at the app level while accommodating merchants with unique business requirements or risk profiles.

Ready to configure scheduled transfers? Transfer schedule settings are managed by the Violet team. To learn more about scheduled transfers or configure a transfer schedule for your app or specific merchants, please reach out to Violet.

Transfer Schedule Settings

require_fulfillment

Controls whether bag fulfillment status is required before transfers are executed.

Value	Behavior
false (default)	Transfers execute immediately after payment capture, regardless of fulfillment status
true	Transfers only execute for bags in SHIPPED or DELIVERED status

When to use require_fulfillment: true:

• You want to ensure merchants are paid only after orders ship

• Your business model involves dropshipping or print-on-demand where fulfillment timing varies

• You want to reduce financial risk from unfulfilled orders

• Merchants have historically had fulfillment issues

time_interval_seconds

Sets the time interval in seconds after which a distribution is eligible to be transferred.

Value	Behavior
0 (default)	Transfers execute immediately (no batching)
86400	Distribution eligible for transfer after 1 day (24 hours)
604800	Distribution eligible for transfer after 7 days (7 days)
Custom value	Any interval in seconds

When to use batched transfers:

• You want to reduce the number of individual transfer transactions

• You want to ensure distributions are held for a certain amount of time before being paid out

• Merchants prefer receiving consolidated payouts

• You're processing high volumes of small orders

How It Works

Architecture Overview

When scheduled transfers are enabled, Violet uses a queued distribution system:

Order Placed → Payment Captured → Distribution Created → Queued for Transfer
                                                              ↓
                                          Nightly Job Checks Eligibility
                                                              ↓
                                    Eligible? → Create Transfer → Merchant Paid
                                    Not Eligible? → Remains Queued

Eligibility Criteria

A queued distribution becomes eligible for transfer when ALL of the following are true:

1. Fulfillment Check (if require_fulfillment: true):

   • Bag status is SHIPPED or DELIVERED

2. Time Interval Check (if time_interval_seconds > 0):

   • This amount of time has passed since the distribution was created

3. Standard Checks:

   • Merchant has a valid, active payout account

   • No holds or restrictions on the merchant account

Processing Schedule

Queued distributions are processed by a nightly job that runs at 11:00 PM UTC daily. The job:

1. Finds all eligible queued distributions

2. Groups distributions by merchant

3. Creates a single transfer per merchant (batching all eligible distributions)

4. Updates distribution and transfer statuses

5. Sends TRANSFER_SENT webhook events

Timing Note: The 11:00 PM UTC processing time means merchants in different time zones will see payouts arrive at different local times. For US-based merchants, this typically means early evening payouts.

Use Cases

Use Case 1: Dropshipping Marketplace

Scenario: A marketplace connects shoppers with dropship merchants who fulfill orders from third-party suppliers. Fulfillment times vary from 2-14 days.

Challenge: With immediate transfers, merchants receive payment before confirming they can fulfill the order. If a supplier is out of stock, the merchant has already been paid.

Solution:

{
  "transfer_schedule": {
    "require_fulfillment": true,
    "time_interval_seconds": 0
  }
}

Result: Merchants receive payment only after marking orders as shipped, ensuring they've confirmed fulfillment capability before receiving funds.

---

Use Case 2: High-Volume, Low-Value Orders

Scenario: A social commerce platform processes thousands of small orders daily, averaging $15-25 per order.

Challenge: Each order generates a separate transfer, creating thousands of micro-transactions. This increases payment processing overhead and makes reconciliation difficult.

Solution:

{
  "transfer_schedule": {
    "require_fulfillment": false,
    "time_interval_seconds": 86400
  }
}

Result: Merchants receive a single daily transfer aggregating all their orders from the past 24 hours, reducing transaction volume by 90%+ and simplifying reconciliation.

---

Use Case 3: Risk-Conscious Marketplace

Scenario: A marketplace has experienced chargebacks and disputes when merchants fail to fulfill orders or ship counterfeit goods.

Challenge: By the time a dispute is raised, funds have already been transferred to the merchant, making recovery difficult.

Solution:

{
  "transfer_schedule": {
    "require_fulfillment": true,
    "time_interval_seconds": 604800
  }
}

Result:

• Funds are held until orders are confirmed shipped

• Weekly batching provides a 7-day buffer for issues to surface

• More time to identify and address problems before merchant payout

---

Use Case 4: Predictable Payout Schedules

Scenario: A B2B marketplace wants to offer merchants predictable "payday" schedules rather than sporadic transfers.

Challenge: Merchants prefer knowing exactly when to expect payments for cash flow planning.

Solution:

{
  "transfer_schedule": {
    "require_fulfillment": false,
    "time_interval_seconds": 604800
  }
}

Result: Merchants receive weekly payouts on a predictable schedule, improving their ability to manage cash flow and plan expenses.

Combining with Transfer Methods

Scheduled transfers work with different transfer methods:

Transfer Method	Scheduled Transfers Behavior
AUTOMATIC	Distributions are queued and processed by the nightly job based on your schedule settings
CUSTOM	Distributions are queued; you can trigger transfers via API or let the nightly job process them
EXTERNAL	Not applicable—transfers handled outside Violet
DISABLED	Not applicable—no distributions created

Monitoring Queued Distributions

Dashboard Visibility

Merchants can view their pending (queued) distributions in the Merchant Dashboard. The distributions will show:

• Status: PENDING (waiting for transfer)

• Associated order and bag information

• Expected payout timing based on your configuration

API Access

Use the Search Distributions API to query queued distributions:

GET /distributions?status=PENDING&merchant_id={merchant_id}

Webhook Events

When scheduled transfers are processed, you'll receive standard transfer webhook events:

• TRANSFER_SENT: Transfer successfully created and sent to merchant

• TRANSFER_FAILED: Transfer failed (includes error details)

Best Practices

Setting Appropriate Intervals

Business Type	Recommended time_interval_seconds
High-volume, small orders	86400 (daily)
Standard e-commerce	0 or 86400
B2B with large orders	604800 (weekly)
Dropship/POD	0 with require_fulfillment: true

Communicating with Merchants

When enabling scheduled transfers, communicate clearly with merchants about:

• When they can expect to receive payouts

• How fulfillment status affects their payouts (if applicable)

• Where to view pending distributions in the dashboard

Handling Edge Cases

Partial Fulfillment: If a bag is partially fulfilled, transfers are only created for the fulfilled portion when require_fulfillment is enabled.

Refunds: Refund distributions are processed separately and follow standard refund timing, not the scheduled transfer settings.

Manual Overrides: You can still trigger transfers manually via the API for urgent situations, bypassing the scheduled processing.

FAQ

Q: What happens to distributions if a merchant doesn't fulfill an order?

A: With require_fulfillment: true, distributions remain in PENDING status indefinitely until the bag is marked as SHIPPED or DELIVERED. Consider implementing processes to handle long-unfulfilled orders.

Q: Can I have different schedules for different merchants?

A: Yes! Transfer schedule settings can be configured at both the app level (applying to all merchants by default) and at the merchant level (overriding app defaults for specific merchants). This allows you to set standard defaults while customizing schedules for merchants with unique requirements. Reach out to Violet to configure merchant-specific transfer schedules.

Q: What time zone does the nightly job use?

A: The processing job runs at 11:00 PM UTC daily. Plan your merchant communications accordingly based on their local time zones.

Q: Can I trigger a transfer manually before the scheduled time?

A: Yes, you can use the Transfer Funds API to manually trigger transfers for specific orders or bags at any time.

Q: How do I enable scheduled transfers for my app?

A: Transfer schedule settings are managed by the Violet team. Reach out to Violet to discuss your requirements and configure scheduled transfer settings for your app or specific merchants.