update capture tasks for enhanced order capabilities (#486)

Author: tekhaus

docs/auto-capture-order-payment-after-x-days/README.md

@@ -30,6 +30,8 @@ shopify/orders/create+{{ options.days_to_wait_before_capturing__number_required
 
 After waiting 7 days (or another timespan of your choice), this task attempts to capture all open authorized payments for an order. (Multiple authorizations can exist on edited orders or with post-purchase upsells.)
 
+If the order is modified before capturing, due to applying discounts, changing shipping fees, and/or making item adjustments, then this task will only capture up to a maximum of the current order total. Refunds that are not associated with an item adjustment are not supported by this task.
+
 ## Installing this task
 
 Find this task [in the library at tasks.mechanic.dev](https://tasks.mechanic.dev/auto-capture-order-payment-after-x-days), and use the "Try this task" button. Or, import [this task's JSON export](../../tasks/auto-capture-order-payment-after-x-days.json) – see [Importing and exporting tasks](https://learn.mechanic.dev/core/tasks/import-and-export) to learn how imports work.

docs/auto-capture-order-payment-after-x-days/script.liquid

@@ -1,9 +1,24 @@
+{% comment %}
+  -- get GraphQL order and transaction data
+{% endcomment %}
+
 {% capture query %}
   query {
     order(id: {{ order.admin_graphql_api_id | json }}) {
       id
       name
       displayFinancialStatus
+      currentTotalPriceSet {
+        presentmentMoney {
+          amount
+        }
+      }
+      totalReceivedSet {
+        presentmentMoney {
+          amount
+          currencyCode
+        }
+      }
       transactions(capturable: true) {
         id
         kind
@@ -28,13 +43,28 @@
           "id": "gid://shopify/Order/1234567890",
           "name": "#SAMPLE",
           "displayFinancialStatus": "AUTHORIZED",
+          "currentTotalPriceSet": {
+            "presentmentMoney": {
+              "amount": "23.45"
+            }
+          },
           "transactions": [
             {
               "id": "gid://shopify/OrderTransaction/1234567890",
               "kind": "AUTHORIZATION",
               "totalUnsettledSet": {
                 "presentmentMoney": {
-                  "amount": "12.34",
+                  "amount": "20.00",
+                  "currencyCode": "USD"
+                }
+              }
+            },
+            {
+              "id": "gid://shopify/OrderTransaction/2345678901",
+              "kind": "AUTHORIZATION",
+              "totalUnsettledSet": {
+                "presentmentMoney": {
+                  "amount": "10.00",
                   "currencyCode": "USD"
                 }
               }
@@ -50,20 +80,60 @@
 
 {% assign order = result.data.order %}
 
+{% comment %}
+  -- the current total price will reflect changes made after the initial sale: discounts, shipping changes, item adjustments
+  -- reducing by total received (i.e. partially paid orders) is for payment gateways that support multiple captures (e.g. Shopify Payments)
+{% endcomment %}
+
+{% assign current_total_price = order.currentTotalPriceSet.presentmentMoney.amount | times: 1.0 %}
+{% assign total_received = order.totalReceivedSet.presentmentMoney.amount | times: 1.0 %}
+{% assign left_to_capture = current_total_price | minus: total_received %}
+
+{% unless event.preview %}
+  {% log
+    current_total_price: current_total_price,
+    total_received: total_received,
+    left_to_capture: left_to_capture
+  %}
+{% endunless %}
+
 {% if order.displayFinancialStatus == "AUTHORIZED" or order.displayFinancialStatus == "PARTIALLY_PAID" %}
   {% assign authorized_transactions = order.transactions | where: "kind", "AUTHORIZATION" %}
 
+  {% comment %}
+    -- multiple authorizations could be on the order due to upsells or item additions
+  {% endcomment %}
+
   {% for transaction in authorized_transactions %}
+    {% comment %}
+      -- capture the unsettled amount of this transaction without exceeding the amount left to capture
+    {% endcomment %}
+
     {% assign unsettled_amount = transaction.totalUnsettledSet.presentmentMoney.amount | times: 1.0 %}
+    {% assign amount_to_capture = unsettled_amount | at_most: left_to_capture %}
+
+    {% unless event.preview %}
+      {% log
+        transaction_id: transaction.id,
+        unsettled_amount: unsettled_amount,
+        amount_to_capture: amount_to_capture
+      %}
+    {% endunless %}
+
+    {% if amount_to_capture > 0 %}
+      {% comment %}
+        -- reduce the amount left to capture by the amount captured for this transaction
+      {% endcomment %}
+
+      {% assign left_to_capture = left_to_capture | minus: amount_to_capture %}
 
-    {% if unsettled_amount > 0 %}
       {% action "shopify" %}
         mutation {
           orderCapture(
             input: {
               id: {{ order.id | json }}
               parentTransactionId: {{ transaction.id | json }}
-              amount: {{ unsettled_amount | json }}
+              amount: {{ amount_to_capture | json }}
               currency: {{ transaction.totalUnsettledSet.presentmentMoney.currencyCode }}
             }
           ) {

docs/capture-all-authorized-payments/README.md

@@ -2,7 +2,7 @@
 
 Tags: Payment
 
-This task will scan for all orders that have a financial status of "authorized", and will capture payment for them. This task can be scheduled to run daily, and can be run on demand.
+This task will scan for all orders that have a financial status of "authorized" or optionally "partially paid", and will attempt to capture all open authorized payments for them. This task can be scheduled to run daily, and can be run on demand.
 
 * View in the task library: [tasks.mechanic.dev/capture-all-authorized-payments](https://tasks.mechanic.dev/capture-all-authorized-payments)
 * Task JSON, for direct import: [task.json](../../tasks/capture-all-authorized-payments.json)
@@ -14,7 +14,7 @@ This task will scan for all orders that have a financial status of "authorized",
 {
   "include_partially_paid_orders__boolean": false,
   "run_daily__boolean": false,
-  "hours_to_wait_after_midnight_when_running_daily__number": null
+  "hours_to_wait_after_midnight_when_running_daily__range_min0_max23_required": 0
 }
 ```
 
@@ -23,17 +23,19 @@ This task will scan for all orders that have a financial status of "authorized",
 ## Subscriptions
 
 ```liquid
-{% if options.run_daily__boolean %}mechanic/scheduler/daily{% if options.hours_to_wait_after_midnight_when_running_daily__number %}+{{ options.hours_to_wait_after_midnight_when_running_daily__number | times: 60 | round }}.minutes{% endif %}{% endif %}
+{% if options.run_daily__boolean %}
+  mechanic/scheduler/daily+{{ options.hours_to_wait_after_midnight_when_running_daily__range_min0_max23_required }}.hours
+{% endif %}
 mechanic/user/trigger
 ```
 
 [Learn about event subscriptions in Mechanic](https://learn.mechanic.dev/core/tasks/subscriptions)
 
 ## Documentation
 
-This task will scan for all orders that have a financial status of "authorized", and will capture payment for them. This task can be scheduled to run daily, and can be run on demand.
+This task will scan for all orders that have a financial status of "authorized" or optionally "partially paid", and will attempt to capture all open authorized payments for them. This task can be scheduled to run daily, and can be run on demand.
 
-This task will scan for all orders that have a financial status of "authorized", and will capture payment for them. Enable "Run daily" to perform this every day at midnight, or use the "Run task" button to perform this scan on demand.
+If an order is modified after creation but before capturing, due to applying discounts, changing shipping fees, and/or making item adjustments, then this task will only capture up to a maximum of the current order total. Refunds that are not associated with an item adjustment are not supported by this task.
 
 ## Installing this task