How to collect remaining preorder payments and handle failed charges

When you offer preorders with partial or deposit payments, the remaining balance needs to be collected before you ship. STOQ gives you two ways to collect that balance: manually from the Reports page, or automatically on a schedule you set. If a charge fails — whether triggered manually or automatically — STOQ sends a payment failure email to the customer and a notification to you. This article explains how auto-collection works, when it runs, what happens when a payment fails, and how to customize the failure notification.

How Payment Collection Works in STOQ

STOQ supports three ways to collect the remaining balance on a preorder with partial payment. Each method is configured per offer in the Payment section of your preorder offer settings.

Manual Collection

When you choose I'll collect manually from Shopify admin or STOQ > Reports, you control exactly when to charge the remaining balance. No automatic charges happen.

To collect payment manually:

1. Go to Reports → Preorders → Orders.
2. Select one or more orders with an outstanding balance.
3. Click Collect payment in the bulk action bar.
4. Confirm the action.

You can also collect payment on a single order:

1. Go to Reports → Preorders → Orders.
2. Click into the order you want to charge.
3. Click the Collect payment button at the top of the order detail page.

What you get back after collecting manually: Once you start a manual collection, STOQ emails you a status report at the address set in Reports → Settings → Email address to receive reports.

• Single order: You receive a notification confirming the result for that order — either that the charge succeeded, or that it failed along with the reason Shopify gave (for example, "Card declined" or "Payment mandate expired").
• Bulk collection: You receive one summary email with a CSV file attached. The CSV lists every order you tried to charge, whether each one succeeded or failed, and a timestamp — so you can see your full results in one place instead of checking orders one by one.

Automatic Collection on a Scheduled Date

When you choose Collect automatically → On the scheduled date, STOQ charges the remaining balance on the payment due date you set in the offer.

• The payment due date is visible to customers at checkout.
• STOQ runs the auto-collection job every hour on the scheduled collection date. It checks each partially paid preorder to see if the payment due date has arrived or has passed.
• The job uses the shop's timezone to determine the current date, so charges align with your local business day.
• Each order is charged only once. If STOQ has already attempted payment collection for an order, it will not retry automatically.

Automatic Collection When the Order Ships

When you choose Collect automatically → When the order ships, STOQ charges the remaining balance as soon as you fulfill the order in Shopify.

• STOQ listens for the Shopify orders/updated webhook. When a line item with an auto-collect-on-fulfillment selling plan is fulfilled, STOQ immediately attempts to capture the outstanding balance.
• This option is useful when you do not know the exact ship date in advance and want to charge customers at the moment you actually ship.

When Does the Auto-Collection Job Run?

STOQ checks for balances to collect once every hour. On the date set for automatic collection, it looks at every shop that has at least one active preorder offer with automatic collection turned on.

For each shop, the job:

1. Finds all partially paid preorder orders with an outstanding balance greater than zero.
2. Checks each order's selling plan to determine the auto-collection type:

• On the scheduled date — STOQ checks whether the payment due date is today or has already passed (using your shop's timezone). If so, it attempts to collect.
• When the order ships — STOQ checks whether the order has already been fulfilled. If it has, and no charge has been attempted yet, it attempts to collect. (This acts as a safety net in case the real-time charge at fulfillment was missed.)

3. Skips any order that already has a payment collection attempt on record (successful, failed, or pending).
4. Attempts to charge the saved payment method through Shopify.

What Happens When Payment Collection Fails

When a payment collection attempt fails — whether triggered manually from STOQ Reports, automatically on the scheduled date, or automatically when the order ships — STOQ sends two notifications:

1. Customer Email — "Payment Collection Failed"

STOQ sends a customizable email to the customer informing them that their remaining balance could not be charged. This email includes a Complete payment button that takes the customer to the Shopify checkout page. On that page, the customer can enter their card details and click Pay now to complete the remaining payment.

This email is sent only when:

• You manually collect payment from Reports → Preorders → Orders in STOQ (single or bulk), or
• Auto-collection is enabled and STOQ triggers the charge automatically (on the scheduled date or when the order ships).

The default email content is:

To customize this email:

1. Go to Preorders → Settings → Notifications.
2. Click Customize email to open the template editor.
3. In the left sidebar, click the Payment collection failed icon (payment icon).
4. Edit the subject, header, message, and button text fields.
5. Use Variables to insert dynamic data like {{order.name}} and {{shop.name}}.
6. Click Save.

2. Merchant Notification — Payment Collection Failed Report

STOQ also sends an email to the merchant (the store owner or the address configured in Reports → Settings → Email address to receive reports). This notification includes the order number and the error message from Shopify explaining why the charge failed (e.g., "Card declined," "Payment mandate expired").

For bulk collection, STOQ sends a single summary email with a CSV attachment listing each order and its payment result (success or failure), along with a timestamp.

How Payment Failure Detection Works

Payment collection through Shopify is asynchronous. When STOQ sends a charge request via the orderCreateMandatePayment mutation, Shopify accepts it immediately but the actual card charge settles later. This means a payment can appear to succeed initially but fail silently afterward (e.g., insufficient funds, expired card).

STOQ handles this with a background reconciliation process:

1. Every payment attempt is recorded with a pending status.
2. A scheduled job checks all pending payment attempts that are between 10 minutes and 24 hours old.
3. For each pending attempt, STOQ queries Shopify's payment status API to check the outcome.
4. If Shopify reports success (authorized, captured, purchased, or refunded), STOQ updates the record to successful.
5. If Shopify reports failure (error, voided, or retryable), STOQ updates the record to failed and sends the payment failure notifications (customer email + merchant email).
6. If Shopify has not settled the payment within 24 hours, STOQ marks the attempt as couldn't verify and stops polling.

This is why you may see three statuses in the Payment collection filter on Reports → Preorders → Orders: Successful, Failed, and Couldn't verify.

Klaviyo Integration for Payment Failure Emails

If you use Klaviyo as your email platform, you can route the payment failure email through a Klaviyo Flow instead of sending it from STOQ.

When a Klaviyo Flow is configured for the payment failure event:

• STOQ triggers the Klaviyo Flow instead of sending its own email.
• You design the email in Klaviyo's editor with full access to Klaviyo's segmentation and A/B testing tools.
• The template editor in STOQ shows a banner confirming that a Klaviyo Flow is configured.

To set this up, go to Preorders → Settings → Integrations → Klaviyo and configure the payment failure flow.

Known Limitations

• Single attempt only. Auto-collection attempts to charge each order once. If the charge fails, STOQ does not automatically retry. You must retry manually or wait for the customer to pay through the failure email link.
• Shopify admin charges do not trigger STOQ emails. If you collect payment directly from Shopify admin (not through STOQ), the STOQ payment failure email is not sent to the customer. Shopify handles its own notifications in that case.
• Async settlement can delay failure detection. Because Shopify settles card charges asynchronously, it may take up to 24 hours for STOQ to detect a failed payment. During this window, the payment status shows as pending.
• Payment due date is required by Shopify. Even if you plan to collect manually, Shopify requires a payment due date for all partial payment selling plans. Customers see this date at checkout.
• Paid STOQ plan required. Automatic payment collection requires a paid STOQ plan.
• Online Store 2.0 theme required. STOQ requires a Shopify Online Store 2.0 or newer theme for app embed functionality.

Troubleshooting

FAQs

Q: When exactly does the auto-collection job run?

A: The auto-collection job runs every hour. On the scheduled collection date, it checks all partially paid preorder orders where the payment due date has arrived or passed (using the shop's timezone). Each order is charged only once — if a prior attempt exists, the job skips that order.

Q: Does STOQ automatically retry failed payments?

A: No. Each order gets a single automatic collection attempt. If the charge fails, you need to retry manually from Reports → Preorders → Orders, or the customer can click the Complete payment button in their failure email to pay through Shopify checkout.

Q: Who receives the payment failure email — the customer or the merchant?

A: Both. The customer receives a customizable "Payment collection failed" email with a link to complete their payment. The merchant receives a separate notification at the email address configured in Reports → Settings with the order number and error details.

Q: Does the payment failure email send if I collect from Shopify admin?

A: No. The STOQ payment failure email is only sent when the charge is initiated through STOQ — either manually from Reports → Preorders → Orders, or automatically via auto-collection. Shopify admin handles its own payment notifications separately.

Q: What does "couldn't verify" mean in the Payment collection filter?

A: It means STOQ could not confirm the outcome of a payment attempt within 24 hours. Shopify did not return a definitive success or failure result. You should check the order in Shopify admin to verify the actual payment status and retry collection if needed.

Q: Can I use Klaviyo for the payment failure email instead of STOQ?

A: Yes. Go to Preorders → Settings → Integrations → Klaviyo and configure the payment failure flow. When configured, STOQ triggers the Klaviyo Flow instead of sending its own email, giving you access to Klaviyo's full design and segmentation tools.

Q: What is the difference between "On the scheduled date" and "When the order ships"?

A: "On the scheduled date" charges the customer on the payment due date you set in the offer (checked daily by the cron job). "When the order ships" charges the customer the moment you fulfill the order in Shopify (triggered in real time by the orders/updated webhook). Choose the option that matches your fulfillment workflow.

Q: Can I change from manual to automatic collection on an existing offer?

A: Yes. Open the offer in Preorders, go to the Payment section, and switch from "I'll collect manually" to "Collect automatically." This change applies to new orders going forward. Existing orders that were placed under the manual setting are not automatically charged — you can still collect those manually.

Updated on: 11/06/2026