Changeset 3752964

Timestamp:

10/18/2026 11:44:47 AM (4 weeks ago)

Author:

demfilz

Message:

Release 1.2.1: gift card and store credit support, order fees synced, 429 retry, bulk stock map

Location:

demfilz-sync-for-quickbooks/trunk

Files:

• demfilz-sync-for-quickbooks.php (modified) (2 diffs)
• includes/admin/class-dwtq-admin.php (modified) (1 diff)
• includes/admin/views/mapping.php (modified) (2 diffs)
• includes/class-dwtq-installer.php (modified) (1 diff)
• includes/providers/class-dwtq-abstract-provider.php (modified) (1 diff)
• includes/providers/class-dwtq-provider-quickbooks.php (modified) (4 diffs)
• includes/sync/class-dwtq-gift-cards.php (added)
• includes/sync/class-dwtq-inventory-sync.php (modified) (1 diff)
• readme.txt (modified) (4 diffs)

demfilz-sync-for-quickbooks/trunk/demfilz-sync-for-quickbooks.php

@@ -4 +4 @@
  * Plugin URI:        https://demfilz.com/demfilz-woo-to-quickbooks
  * Description:       Send WooCommerce orders, customers and stock to QuickBooks Online via the official Intuit API. Free manual sync; Pro adds automation.
- * Version:           1.2.0
+ * Version:           1.2.1
  * Requires at least: 6.2
  * Requires PHP:      7.2
@@ -19 +19 @@
 defined( 'ABSPATH' ) || exit;
 
-define( 'DWTQ_VERSION', '1.2.0' );
+define( 'DWTQ_VERSION', '1.2.1' );
 define( 'DWTQ_FILE', __FILE__ );
 define( 'DWTQ_DIR', plugin_dir_path( __FILE__ ) );

demfilz-sync-for-quickbooks/trunk/includes/admin/class-dwtq-admin.php

@@ -209 +209 @@
                 Dwtq_Settings::update(
                         array(
-                                'default_item'     => isset( $_POST['default_item'] ) ? sanitize_text_field( wp_unslash( $_POST['default_item'] ) ) : '',
-                                'default_tax_code' => isset( $_POST['default_tax_code'] ) ? sanitize_text_field( wp_unslash( $_POST['default_tax_code'] ) ) : '',
-                                'freight_tax_code' => isset( $_POST['freight_tax_code'] ) ? sanitize_text_field( wp_unslash( $_POST['freight_tax_code'] ) ) : '',
-                                'sale_type'        => isset( $_POST['sale_type'] ) ? sanitize_text_field( wp_unslash( $_POST['sale_type'] ) ) : 'Invoice',
+                                'default_item'       => isset( $_POST['default_item'] ) ? sanitize_text_field( wp_unslash( $_POST['default_item'] ) ) : '',
+                                'default_tax_code'   => isset( $_POST['default_tax_code'] ) ? sanitize_text_field( wp_unslash( $_POST['default_tax_code'] ) ) : '',
+                                'freight_tax_code'   => isset( $_POST['freight_tax_code'] ) ? sanitize_text_field( wp_unslash( $_POST['freight_tax_code'] ) ) : '',
+                                'gift_card_item'     => isset( $_POST['gift_card_item'] ) ? sanitize_text_field( wp_unslash( $_POST['gift_card_item'] ) ) : '',
+                                'gift_card_tax_code' => isset( $_POST['gift_card_tax_code'] ) ? sanitize_text_field( wp_unslash( $_POST['gift_card_tax_code'] ) ) : '',
+                                'sale_type'          => isset( $_POST['sale_type'] ) ? sanitize_text_field( wp_unslash( $_POST['sale_type'] ) ) : 'Invoice',
                         )
                 );

demfilz-sync-for-quickbooks/trunk/includes/admin/views/mapping.php

@@ -23 +23 @@
 $dwtq_tax       = Dwtq_Settings::get( 'default_tax_code' );
 $dwtq_freight   = Dwtq_Settings::get( 'freight_tax_code' );
+$dwtq_gift_item = Dwtq_Settings::get( 'gift_card_item' );
+$dwtq_gift_tax  = Dwtq_Settings::get( 'gift_card_tax_code' );
 
 if ( ! function_exists( 'dwtq_render_select' ) ) :
@@ -73 +75 @@
                         <td><?php dwtq_render_select( 'freight_tax_code', $dwtq_taxes, $dwtq_freight ); ?></td>
                 </tr>
+                <tr>
+                        <th><?php esc_html_e( 'Gift card item', 'demfilz-sync-for-quickbooks' ); ?></th>
+                        <td>
+                                <?php dwtq_render_select( 'gift_card_item', $dwtq_items, $dwtq_gift_item ); ?>
+                                <p class="description"><?php esc_html_e( 'Only needed if you sell gift cards or accept gift cards or store credit (Demfilz Gift Cards and Store Credit). In QuickBooks, create a Non-inventory or Service item named "Gift card" whose income account is a liability account, for example "Gift card liability". Gift cards sold post to it instead of income, and amounts paid by gift card or store credit post as a negative line for it, so your revenue and tax stay complete and the sale total matches what the customer was charged.', 'demfilz-sync-for-quickbooks' ); ?></p>
+                        </td>
+                </tr>
+                <tr>
+                        <th><?php esc_html_e( 'Gift card tax code', 'demfilz-sync-for-quickbooks' ); ?></th>
+                        <td>
+                                <?php dwtq_render_select( 'gift_card_tax_code', $dwtq_taxes, $dwtq_gift_tax ); ?>
+                                <p class="description"><?php esc_html_e( 'Choose a code with no tax, such as Out of scope or Not reportable. Leave blank to use the item default.', 'demfilz-sync-for-quickbooks' ); ?></p>
+                        </td>
+                </tr>
         </table>
         <p class="description"><?php esc_html_e( 'Free tier maps all lines to one tax code. Pro adds per-product / per-tax-class rules. Leave tax codes blank if your QuickBooks region does not use tax codes on sales.', 'demfilz-sync-for-quickbooks' ); ?></p>

demfilz-sync-for-quickbooks/trunk/includes/class-dwtq-installer.php

@@ -80 +80 @@
         public static function default_settings() {
                 return array(
-                        'environment'      => 'production', // Intuit environment: production or sandbox.
-                        'sale_type'        => 'Invoice',    // Sale document type: Invoice, SalesReceipt or Estimate.
-                        'default_item'     => '',           // QuickBooks item id used for line items.
-                        'default_tax_code' => '',           // QuickBooks tax code id.
-                        'freight_tax_code' => '',           // QuickBooks tax code id for shipping.
-                        'auto_sync_status' => array( 'processing', 'completed' ), // Statuses that trigger auto sync in Pro.
+                        'environment'        => 'production', // Intuit environment: production or sandbox.
+                        'sale_type'          => 'Invoice',    // Sale document type: Invoice, SalesReceipt or Estimate.
+                        'default_item'       => '',           // QuickBooks item id used for line items.
+                        'default_tax_code'   => '',           // QuickBooks tax code id.
+                        'freight_tax_code'   => '',           // QuickBooks tax code id for shipping.
+                        'gift_card_item'     => '',           // QuickBooks item id (its account is a liability) for gift cards sold and redeemed.
+                        'gift_card_tax_code' => '',           // QuickBooks tax code id for gift card lines (no tax).
+                        'auto_sync_status'   => array( 'processing', 'completed' ), // Statuses that trigger auto sync in Pro.
                 );
         }

demfilz-sync-for-quickbooks/trunk/includes/providers/class-dwtq-abstract-provider.php

@@ -113 +113 @@
                 }
 
-                $response = wp_remote_request( $url, $args );
-                if ( is_wp_error( $response ) ) {
-                        return $response;
-                }
+                // QuickBooks throttles to 500 requests/minute per company and replies 429 with
+                // a Retry-After header. Wait and retry a couple of times so a brief throttle does
+                // not fail the sync. Waits are bounded, and larger in background (cron) context
+                // than interactive so a manual click never hangs for long.
+                $max_wait = function_exists( 'wp_doing_cron' ) && wp_doing_cron() ? 60 : 10;
+                $attempts = 0;
+                do {
+                        $response = wp_remote_request( $url, $args );
+                        if ( is_wp_error( $response ) ) {
+                                return $response;
+                        }
+                        $status = (int) wp_remote_retrieve_response_code( $response );
+                        if ( 429 !== $status || $attempts >= 2 ) {
+                                break;
+                        }
+                        $wait = (int) wp_remote_retrieve_header( $response, 'retry-after' );
+                        if ( $wait <= 0 ) {
+                                $wait = 5;
+                        }
+                        if ( $wait > $max_wait ) {
+                                break;
+                        }
+                        ++$attempts;
+                        sleep( $wait ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.runtime_configuration, WordPressVIPMinimum.Performance.LowExpiryCacheTime.sleep -- Deliberate rate-limit backoff, bounded above.
+                } while ( true );
 
                 $status = (int) wp_remote_retrieve_response_code( $response );
                 $raw    = wp_remote_retrieve_body( $response );
                 $data   = '' !== $raw ? json_decode( $raw, true ) : array();
+
+                if ( 429 === $status ) {
+                        $retry = (int) wp_remote_retrieve_header( $response, 'retry-after' );
+                        $msg   = $retry > 0
+                                /* translators: %d: number of seconds to wait. */
+                                ? sprintf( __( 'QuickBooks is rate-limiting requests (429). Please wait %d seconds and try again.', 'demfilz-sync-for-quickbooks' ), $retry )
+                                : __( 'QuickBooks is rate-limiting requests (429). Please wait a minute and try again.', 'demfilz-sync-for-quickbooks' );
+                        return new WP_Error(
+                                'dwtq_api_rate_limit',
+                                $msg,
+                                array(
+                                        'status'      => 429,
+                                        'retry_after' => $retry,
+                                )
+                        );
+                }
 
                 if ( $status < 200 || $status >= 300 ) {

demfilz-sync-for-quickbooks/trunk/includes/providers/class-dwtq-provider-quickbooks.php

@@ -139 +139 @@
          */
         protected function sale_lines( $order ) {
-                $lines    = array();
-                $tax_map  = new Dwtq_Tax_Mapper();
-                $item_ref = Dwtq_Settings::get( 'default_item' );
+                $lines     = array();
+                $tax_map   = new Dwtq_Tax_Mapper();
+                $item_ref  = Dwtq_Settings::get( 'default_item' );
+                $gift_item = Dwtq_Settings::get( 'gift_card_item' );
+                $gift_tax  = Dwtq_Settings::get( 'gift_card_tax_code' );
 
                 foreach ( $order->get_items() as $item ) {
-                        $detail = array( 'ItemRef' => array( 'value' => $item_ref ) );
-                        $tax    = $tax_map->code_uid_for_item( $order, $item );
+                        // A gift card being sold is money held for the customer: it goes on the gift card
+                        // item, whose account is a liability, not on the income item.
+                        $gift_sale = Dwtq_Gift_Cards::is_gift_card_sale( $item );
+                        $detail    = array( 'ItemRef' => array( 'value' => $gift_sale ? $gift_item : $item_ref ) );
+                        $tax       = $gift_sale ? $gift_tax : $tax_map->code_uid_for_item( $order, $item );
                         if ( $tax ) {
                                 $detail['TaxCodeRef'] = array( 'value' => $tax );
                         }
+                        $total   = round( (float) $order->get_line_total( $item, false ), 2 );
+                        $face    = $gift_sale ? Dwtq_Gift_Cards::face_value( $item, $total ) : $total;
                         $lines[] = array(
                                 'DetailType'          => 'SalesItemLineDetail',
-                                'Amount'              => round( (float) $order->get_line_total( $item, false ), 2 ),
+                                'Amount'              => $face,
                                 'Description'         => $item->get_name(),
                                 'SalesItemLineDetail' => $detail,
                         );
+
+                        // A card sold below its value (on sale or with a coupon): the difference is a
+                        // discount, on the income item.
+                        if ( $face > $total ) {
+                                $amount = -1 * round( $face - $total, 2 );
+                                $detail = array(
+                                        'ItemRef'   => array( 'value' => $item_ref ),
+                                        'Qty'       => 1,
+                                        'UnitPrice' => $amount,
+                                );
+                                if ( $gift_tax ) {
+                                        $detail['TaxCodeRef'] = array( 'value' => $gift_tax );
+                                }
+                                $lines[] = array(
+                                        'DetailType'          => 'SalesItemLineDetail',
+                                        'Amount'              => $amount,
+                                        /* translators: %s: product name. */
+                                        'Description'         => sprintf( __( 'Discount on %s', 'demfilz-sync-for-quickbooks' ), $item->get_name() ),
+                                        'SalesItemLineDetail' => $detail,
+                                );
+                        }
                 }
 
@@ -171 +199 @@
                 }
 
+                // Fees / surcharges (e.g. a payment surcharge added as a WooCommerce fee). A negative
+                // fee (a discount-style fee) posts as a negative line.
+                $fee_tax = Dwtq_Settings::get( 'default_tax_code' );
+                foreach ( $order->get_fees() as $fee ) {
+                        $amount = round( (float) $fee->get_total(), 2 );
+                        if ( 0.0 === $amount ) {
+                                continue;
+                        }
+                        $detail = array(
+                                'ItemRef'   => array( 'value' => $item_ref ),
+                                'Qty'       => 1,
+                                'UnitPrice' => $amount,
+                        );
+                        if ( $fee_tax ) {
+                                $detail['TaxCodeRef'] = array( 'value' => $fee_tax );
+                        }
+                        $lines[] = array(
+                                'DetailType'          => 'SalesItemLineDetail',
+                                'Amount'              => $amount,
+                                'Description'         => $fee->get_name() ? $fee->get_name() : __( 'Fee', 'demfilz-sync-for-quickbooks' ),
+                                'SalesItemLineDetail' => $detail,
+                        );
+                }
+
+                // Amounts paid by gift card or store credit: a negative line on the gift card item, so
+                // the payment comes out of the gift card liability, the sale keeps its full revenue and
+                // tax, and the sale total matches the order total.
+                foreach ( Dwtq_Gift_Cards::payments( $order ) as $payment ) {
+                        $amount = -1 * round( (float) $payment['amount'], 2 );
+                        $detail = array(
+                                'ItemRef'   => array( 'value' => $gift_item ),
+                                'Qty'       => 1,
+                                'UnitPrice' => $amount,
+                        );
+                        if ( $gift_tax ) {
+                                $detail['TaxCodeRef'] = array( 'value' => $gift_tax );
+                        }
+                        $lines[] = array(
+                                'DetailType'          => 'SalesItemLineDetail',
+                                'Amount'              => $amount,
+                                'Description'         => $payment['label'],
+                                'SalesItemLineDetail' => $detail,
+                        );
+                }
+
                 return $lines;
         }
@@ -185 +258 @@
                 if ( '' === (string) Dwtq_Settings::get( 'default_item' ) ) {
                         return new WP_Error( 'dwtq_no_item', __( 'Choose a default QuickBooks product/service on the Mapping tab before syncing.', 'demfilz-sync-for-quickbooks' ) );
+                }
+                if ( '' === (string) Dwtq_Settings::get( 'gift_card_item' ) && Dwtq_Gift_Cards::order_uses_gift_cards( $order ) ) {
+                        return new WP_Error( 'dwtq_no_gift_card_item', __( 'This order sells a gift card or was paid partly by gift card or store credit. Choose a gift card item (one whose account is a liability account) on the Mapping tab, then sync the order again.', 'demfilz-sync-for-quickbooks' ) );
                 }
 
@@ -281 +357 @@
 
         /**
+         * Fetch every stock-tracked QuickBooks item in a few paginated calls and return
+         * a SKU => quantity-on-hand map. Lets a bulk stock sync match locally instead of
+         * one API query per product (which blows QuickBooks' per-minute throttle).
+         *
+         * @return array|WP_Error Map of SKU (string) => QtyOnHand (float).
+         */
+        public function get_stock_map() {
+                $map   = array();
+                $start = 1;
+                $page  = 1000;
+                // Cap pages so a runaway/huge catalogue cannot loop forever.
+                for ( $i = 0; $i < 50; $i++ ) {
+                        $data = $this->query( "SELECT * FROM Item WHERE Type = 'Inventory' STARTPOSITION " . $start . ' MAXRESULTS ' . $page );
+                        if ( is_wp_error( $data ) ) {
+                                return $data;
+                        }
+                        $items = isset( $data['Item'] ) && is_array( $data['Item'] ) ? $data['Item'] : array();
+                        foreach ( $items as $item ) {
+                                if ( empty( $item['Sku'] ) || ! isset( $item['QtyOnHand'] ) ) {
+                                        continue;
+                                }
+                                $map[ (string) $item['Sku'] ] = (float) $item['QtyOnHand'];
+                        }
+                        if ( count( $items ) < $page ) {
+                                break;
+                        }
+                        $start += $page;
+                }
+                return $map;
+        }
+
+        /**
          * List tax codes (id => name).
          *

demfilz-sync-for-quickbooks/trunk/includes/sync/class-dwtq-inventory-sync.php

@@ -66 +66 @@
                 return $qty;
         }
+
+        /**
+         * Bulk-pull stock for many products from ONE QuickBooks item map (no per-product
+         * API call). Fetches the SKU => quantity map once (unless passed in) and matches
+         * each product locally. Used by the Pro scheduled sweep and the "Sync all stock"
+         * button to stay under QuickBooks' per-minute throttle.
+         *
+         * @param int[]|null $product_ids Product ids to update (null = all published).
+         * @param array|null $map         Pre-fetched SKU => qty map (null = fetch now).
+         * @return array|WP_Error { updated, skipped, missing } on success.
+         */
+        public function pull_bulk( $product_ids = null, $map = null ) {
+                if ( null === $map ) {
+                        $provider = Dwtq_Provider_Factory::make();
+                        if ( is_wp_error( $provider ) ) {
+                                return $provider;
+                        }
+                        $map = $provider->get_stock_map();
+                        if ( is_wp_error( $map ) ) {
+                                return $map;
+                        }
+                }
+
+                if ( null === $product_ids ) {
+                        $product_ids = wc_get_products(
+                                array(
+                                        'status' => 'publish',
+                                        'limit'  => -1,
+                                        'return' => 'ids',
+                                )
+                        );
+                }
+
+                $updated = 0;
+                $skipped = 0;
+                $missing = 0;
+                foreach ( (array) $product_ids as $pid ) {
+                        $product = wc_get_product( $pid );
+                        if ( ! $product ) {
+                                continue;
+                        }
+                        $sku = $product->get_sku();
+                        if ( '' === $sku ) {
+                                ++$skipped;
+                                continue;
+                        }
+                        if ( ! array_key_exists( $sku, $map ) ) {
+                                ++$missing;
+                                continue;
+                        }
+                        $product->set_manage_stock( true );
+                        $product->set_stock_quantity( $map[ $sku ] );
+                        $product->save();
+                        ++$updated;
+                }
+
+                return array(
+                        'updated' => $updated,
+                        'skipped' => $skipped,
+                        'missing' => $missing,
+                );
+        }
 }

demfilz-sync-for-quickbooks/trunk/readme.txt

@@ -6 +6 @@
 Requires PHP: 7.2
 Requires Plugins: woocommerce
-Stable tag: 1.2.0
+Stable tag: 1.2.1
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
@@ -74 +74 @@
 No. The free version handles connecting, pushing an order, customer sync and stock pull. You only need a QuickBooks Online company to connect to (a free trial or the Intuit sandbox company works). Pro is an optional separate add-on that unlocks automation.
 
+= Does it handle gift cards and store credit? =
+Yes, with Demfilz Gift Cards and Store Credit for WooCommerce. A gift card is a payment, not a discount. In QuickBooks, create a Non-inventory or Service item called "Gift card" whose income account is a liability account (for example "Gift card liability"), then choose it on the Mapping tab with a tax code that has no tax. Gift cards sold post to that item instead of income. When an order is paid partly by gift card or store credit, the sale keeps every product and shipping line with its tax, and the amount paid by card is a negative line for the gift card item, so the sale total matches what the customer paid at checkout. Until the item is chosen, orders that use gift cards are not synced and the log says why.
+
 == Screenshots ==
 
@@ -82 +85 @@
 
 == Changelog ==
+
+= 1.2.1 =
+* New: gift card and store credit support for Demfilz Gift Cards and Store Credit for WooCommerce. Gift cards sold post to a gift card item whose account is a liability, and amounts paid by gift card or store credit post as a negative line for that item, so revenue and tax stay complete and the sale total matches the order total. Choose the item on the Mapping tab. Developers can report another gift card plugin's payments with the dwtq_gift_card_payments filter.
+* A gift card sold below its value (on sale or with a coupon) posts its full value to the gift card account and the difference as a discount on income, so the account always holds what customers can spend.
+* Fix: order fees (for example a payment surcharge) are now synced as lines on the default item with the default tax code, so an order with a fee no longer syncs below its order total. Negative (discount-style) fees post as negative lines.
+* QuickBooks rate limits (429): a throttled request now waits for the time QuickBooks asks for and tries again, up to twice (up to 60 seconds in background jobs, 10 seconds when you click a button), then shows a clear "wait and try again" message instead of a raw API error.
+* Stock can now be read for the whole catalogue from one paginated QuickBooks item list instead of one request per product (used by the Pro scheduled stock sync), which keeps large catalogues under the QuickBooks request limit.
 
 = 1.2.0 =
@@ -110 +120 @@
 == Upgrade Notice ==
 
+= 1.2.1 =
+Adds gift card and store credit support. If you use Demfilz Gift Cards and Store Credit, choose a gift card item on the Mapping tab.
+
 = 1.1.0 =
 Adds supplier-bill sync (with Demfilz Auto Order) and connects Pro to live billing.