Guides

Auto Capture Triggers

Configure your campaign to automatically capture authorized transactions based on a trigger event — for example, when a shipment receives tracking.

When using auth/capture flows, an order is first authorized — placing a hold on the customer's card without collecting payment — and then later captured to actually collect the funds. The capture step can happen in a few different ways: you can call it manually whenever you're ready, you can schedule it for a specific time via the API, or you can let Vrio handle it for you with an Auto Capture Trigger.

Auto Capture Triggers are rules that capture authorized transactions automatically based on an event — without you needing to make a manual capture call or schedule a date. The trigger watches for the event you select and fires the capture as soon as it happens, so payment collection stays tied to whatever business condition matters most to you (for example, a shipment going out the door).

Today, Vrio supports one trigger type:

  • On Shipment Shipped — captures the authorization when a shipment on the order receives a tracking number.

Regardless of which trigger type is configured, an authorization can always be captured manually before the trigger fires — either from the customer view UI or via the API. See Capturing Without a Trigger below.

Auth vs. Sale

Setting an Auto Capture Trigger does not change how orders are processed — it does not force orders into the auth-capture flow. The trigger only applies when an order is actually processed as an authorization. If the same order is processed as a regular sale, the sale charges immediately and the trigger has no effect — there is nothing to capture later.

Whether an order is processed as an auth or a sale is decided at the time of processing (for example, by passing action: "authorize" via the API). The Auto Capture Trigger setting is what determines what happens after an auth is processed, not whether an auth is processed in the first place.

→ Learn more: Auth & Capture transaction types

Configuration

Auto Capture Triggers can be configured in two places:

  • On the campaign — Set the trigger on the Processing tab to apply Auto Capture to every order on the campaign that is processed as an authorization.

  • Per-order via the API — Pass auto_capture_trigger_id on an individual order to override the campaign default.

API Override

You don't have to use the campaign setting for every order. The auto_capture_trigger_id field can be passed directly through the API when creating or updating an order:

  • Enable per-order — Pass auto_capture_trigger_id=1 on an order to enable auto-capture even if the campaign doesn't have it configured. This is useful when only certain orders on a campaign need the auth-capture flow.
  • Disable per-order — Pass auto_capture_trigger_id=0 on an order to disable auto-capture even if the campaign has it enabled. The order will follow the normal sale flow.

If auto_capture_trigger_id is not passed in the API, the order inherits the campaign's setting automatically.

Auto Capture on Recurring

This checkbox controls how recurring cycles (cycle 2+) behave after a captured authorization. It applies regardless of which trigger type is used and regardless of whether the initial auth-capture was driven by the campaign setting or the API override — once an authorization has been captured, this setting determines what cycle 2+ looks like.

When enabled, recurring transactions following a captured authorization also process as authorizations. The same trigger applies — the recurring auth waits for its trigger event before the capture is processed. This creates a consistent auth-capture flow across all billing cycles.

When disabled, only the initial transaction (cycle 1) uses the auth-capture flow. All subsequent recurring cycles process as regular sales and are charged immediately.

If a recurring authorization is declined, it follows the same dunning flow as a declined sale — the transaction type doesn't change how dunning works. Learn more: Dunning Profiles →

Choosing the Right Setting

Enable "Auto Capture on Recurring" if you want every billing cycle to wait for the trigger event before charging. This is ideal for subscription boxes or products where fulfillment timing matters for every shipment. Leave it disabled if you only need auth-capture for the initial order and want recurring cycles to charge immediately.

On Shipment Shipped

The On Shipment Shipped trigger captures the authorization when a shipment on the order receives a tracking number. This trigger ties payment collection to fulfillment — customers are only charged once their order has actually shipped.

This is useful for businesses that want to verify fulfillment before collecting funds, reduce chargebacks from unfulfilled orders, or comply with payment regulations that require shipment before charge.

When setting this trigger on an order via the API, pass auto_capture_trigger_id=1.

How It Works

Standard Auth Flow (Without a Trigger)

  1. Customer places an order as an authorization
  2. Payment is authorized — funds are held on the customer's card but not collected. No shipment is created yet.
  3. The capture is processed (manually, via the API, or via a scheduled date_auto_capture)
  4. On successful capture, the shipment is created and sent to fulfillment

Auth with On Shipment Shipped Flow

  1. Customer places an order as an authorization
  2. Payment is authorized — funds are held on the customer's card but not collected
  3. Shipment is created and sent to fulfillment
  4. Fulfillment ships the order and adds a tracking number
  5. The system detects tracking on the shipment and marks the order ready for capture
  6. The auto capture batch job runs and captures the authorization — funds are collected
Orders with Multiple Shipments

If an order has multiple shipments — for example, items routed to different fulfillment connections — the capture fires when the first shipment receives tracking. The system does not wait for every shipment to ship before capturing.

Shipments on Authorization

This trigger is unique among Auto Capture Triggers in that shipments are created when the authorization is processed, before payment is collected. In every other capture flow — including a regular sale, a capture, or any future trigger that doesn't depend on shipment events — shipments are created at the time payment is collected.

This means your fulfillment provider receives the order and begins packing and shipping while the customer's payment is still only a hold. Once the shipment receives tracking, the system captures the authorization and collects payment.

Fulfillment Before Payment

Because shipments go out before the capture, there is a risk that the capture could fail after the product has already shipped (for example, if the customer's card expires between the auth and capture). Make sure your business model and return policy account for this possibility. See Failed Captures below for how the system handles this scenario.

Voiding and Re-Authorization

Automatic Voiding on Re-Auth

When using the On Shipment Shipped trigger, if a new authorization is processed on an order that already has an uncaptured authorization, the system automatically cleans up the previous state:

  1. All previous uncaptured authorizations are voided — the holds are released
  2. All shipments tied to those voided authorizations are cancelled
  3. New shipments are created for the new authorization

This ensures there is only one active authorization at a time and prevents duplicate shipments from going to fulfillment.

How this differs from the standard auth/capture flow

In the standard auth/capture flow (no trigger), previous authorizations are not voided when a new auth is processed — they stay in place until capture, at which point only the most recent successful auth is captured and the rest are voided. With On Shipment Shipped, the void has to happen immediately on re-auth because shipments have already been scheduled against the prior auth. Leaving those shipments in place would risk duplicate orders going out to the customer.

→ Learn more: Multiple authorizations on a single order

This is particularly important for upsell flows — when a customer accepts an upsell, a new authorization is created at the higher amount. The previous authorization and its shipments are automatically cleaned up.

Learn more: Single Order Upsell Processing →

Re-Auth Restrictions

You cannot re-authorize an order if shipments have already passed their scheduled fulfillment date. At that point, the original shipments may already be in transit — creating new ones would risk sending duplicate orders to the customer.

To give yourself a window where re-authorization is still safe, set a fulfillment delay on the offer. The delay sets how long shipments wait before being sent to fulfillment, so any re-auths that happen within that window automatically clean up and recreate the shipments before they go out. This is especially important for upsell flows, where the order amount may change after the initial auth.

Learn more: Fulfillment Delays →

If you need to make changes after shipments have gone out, void the existing authorization first (which cancels its shipments), then create a new authorization.

Failed Captures

With a failed capture, the authorization was successful — the customer's card was verified and funds were held at the time of the auth. The capture failed for a different reason: the card expired between auth and capture, the customer's available balance dropped, or the processor rejected the capture request.

Because the shipment has already gone out to the customer, the system treats the billing cycle as a success. The customer received their product, so the cycle is considered fulfilled — the failed capture is a payment-collection issue to chase down separately, not a reason to halt the subscription:

  • The order offer remains Active (for subscriptions) or Complete (for one-time sales)
  • The order is marked as Complete
  • The next recurring cycle is scheduled automatically:
    • If "Auto Capture on Recurring" is enabled, the next cycle is an authorization
    • If disabled, the next cycle is a regular sale

Reattempting a Failed Capture

After a capture fails, the Capture button remains available on the authorization in the customer view. You can click it to attempt the capture again at any time, or call POST /orders/{order_id}/capture directly to retry via the API. If the reattempt also fails, no additional recurring cycles are scheduled — the system already scheduled the next cycle when the first capture attempt failed.

What You'll See in the UI

When an authorization has a declined capture:


  • The transaction row shows a Failed status with a red indicator
  • The Capture action button is still available for reattempting
  • The next recurring transaction appears as scheduled in the subscription

Capturing Without a Trigger

You don't have to use a trigger to capture an authorization. Captures can also be processed manually or scheduled directly via the API. See Ways to Capture an Authorization for the manual and API-scheduled paths.

Important Notes

  • The merchant account must be active at the time of capture for it to process successfully.
  • Voiding an authorization releases the hold on funds and cancels its shipments. If a shipment has not yet been sent to the fulfillment connection, the cancel is processed on Vrio's end. If it has already been sent, Vrio attempts to cancel it at the fulfillment connection — but cancellation success depends on the connection and is not always guaranteed. A new authorization must be created if you still need to collect payment.
  • If an order is cancelled after authorization but before capture, the batch may still capture the transaction (since the shipment was already sent with tracking), but no further recurring cycles will be scheduled.

Related Documentation

Updated about 2 hours ago