Actions are what a workflow does when its conditions are true. A workflow needs at least one action, and you can add as many as you like. They run in the order listed. If one fails, the rest of that workflow’s actions are skipped.
| Action | Code | Does |
|---|---|---|
| Add to Queue | queue_add |
Adds the order to a queue. Does nothing if it’s already there. |
| Move to Queue | queue_move |
Removes the order from every queue, then adds it to the one you choose. |
| Remove from Queue | queue_remove |
Removes the order from one queue. |
| Remove from All Queues | queue_remove_all |
Removes the order from every queue. |
| Add Note | note_add |
Adds a note to the order. |
| Set Custom Field | customfield_set |
Sets an order custom field. |
| Webhook (GET) | webhook_get |
Calls a URL with the order ID. |
| Webhook (POST) | webhook_post_order |
Posts the full order as JSON to a URL. |
| Payment Actions | payment |
Captures or refunds payment to match what has shipped or been returned. |
| VOID | void |
Voids the order’s open authorizations. |
Queue actions#
Queue actions name the queue by code. The queue has to exist when you save the workflow. If it’s deleted later, the action fails each time it runs.
Choose between Add and Move with care. Move to Queue clears every queue the order is in, including queues other workflows manage. Use Add to Queue plus Remove from Queue when an order should keep its other queues.
Add Note#
Adds the text you enter as an order note, exactly as typed; there are no variables to fill in. The note is added every time the action runs.
Set Custom Field#
Sets one order custom field to a value. Choose the module and field; the module must be active, installed in the store and provide order fields, such as the Custom Fields module.
Order Workflow queues are custom fields too, so Set Custom Field on an orderworkflow field adds the order to that queue (any true value) or removes it (an empty or false value).
Webhooks#
Webhook (GET) calls your URL with Order_ID=<id> added to the query string and sends no order data. Webhook (POST) sends the whole order as JSON. Either can log in to an endpoint behind HTTP basic authentication. See Webhooks.
Payment actions#
Payment Actions keep captured funds in line with the order’s fulfillment. Each time the action runs, Miva works out how much should be captured so far, compares it with what has been captured, then captures the difference or refunds the excess.
Typical uses:
- Capture as items ship: trigger on Order Shipment Status Change, capture the amount of shipped shipments.
- Capture everything once all items have shipped.
- Refund as returns are received: trigger on Order Return Status Change.
Settings#
| Setting | Default | Meaning |
|---|---|---|
| Capture | Off | Allow the action to capture. |
| Refund | Off | Allow the action to refund. |
| Collected Amount Includes | Required | What should be captured: Entire Order Amount, Amount Of All Created Shipments (items being picked or shipped) or Amount Of All Shipped Shipments. |
| Capture Non-Tax Charges | First | With a shipment-based option, whether shipping, handling and other order charges are captured with the first capture or the last one. |
| If Capture Amount Is Within X Dollars Of Total, Capture All | 0.00 | When what’s left to capture is this close to the order total, capture the full total instead of leaving a small remainder. |
| Collected Amount Excludes | Required | Which returns reduce the amount: created returns (RMA issued) or received returns only. |
| Refund Order Charges When Entire Order Is Returned | All off | Separate switches for shipping, handling, payment, non-item-level tax and other charges. When every item is cancelled or returned, the charges you switch on are refunded and the rest are kept. |
| Prorate Order-Level Discounts | Off | Spread order-level discounts across items in proportion to each item’s subtotal, so partial captures include their share of the discount. |
| Add Payment Operation Notes to Order | Off | Add a note describing each capture or refund. |
How the amount is worked out#
-
Items. Each item counts as its price times quantity, plus its tax and option prices. Whether an item counts depends on its status:
Item status Counted Shipped, gift certificate, digital Always Picking With Entire Order Amount or Amount Of All Created Shipments Pending, backordered, adjustment With Entire Order Amount only RMA issued Only when returns are excluded on receipt (received returns) Cancelled, returned Never -
Charges. Order charges are grouped as shipping, handling, payment, tax and other. Item-level tax is already in the item amounts, so it isn’t counted twice. Negative charges (discounts) are taken off, or spread across items when prorating is on.
- Target. The amount to have captured is the counted items plus charges as set above. If that reaches the order total, or comes within the “within X dollars” amount, the target is the full total.
- Difference. If the target is more than what’s been captured, Miva captures the difference from the order’s authorizations (only if Capture is on). If it’s less, Miva refunds from the order’s captured payments (only if Refund is on).
Requirements and records#
- The payment module has to support capture, refund and void operations. Older payment modules can capture but not refund or void.
- Orders with legacy payment transactions can’t use payment actions. The action adds a note saying so and stops.
- Every run is recorded in the order’s read-only Audit Log custom field: the settings used, the calculated amount, each item and charge, and the payments before and after.
- A failed capture or refund stops the workflow’s remaining actions. With notes on, the note includes the gateway’s error.
VOID#
Voids the remaining amount of every open authorization on the order, for example when an order is cancelled before it ships. Turn on Add notes to record the amounts voided. Like payment actions, VOID is recorded in the Audit Log, needs a payment module that supports voids, and doesn’t work on orders with legacy payment transactions.