[2025-10 CAAPI] Payment schedule balance and due status fields

[juanpprieto]

Overview

Customer Account API 2025-10 adds detailed balance tracking for payment schedules.

API Version

• Version: 2025-10
• API: Customer Account API
• Type: New Feature
• Action Required: No
• Changelog: https://developers.shopify.com/api-changelog/new-balance-and-due-status-fields-for-paymentschedule

What Changed

Three new fields on PaymentSchedule:

• balanceDue - amount currently due
• totalBalance - total outstanding balance
• due - boolean indicating if payment is currently due

Impact on Hydrogen

Customer orders

Current skeleton queries:

• templates/skeleton/app/graphql/customer-account/CustomerOrderQuery.ts
• templates/skeleton/app/graphql/customer-account/CustomerOrdersQuery.ts

May include payment schedule data for subscription orders.

Use case

Relevant for:

• Subscription orders with payment plans
• Shop Pay installments
• B2B payment terms

Investigation Required

Check if payment schedules are queried

• Search for PaymentSchedule in customer account queries
• Verify if skeleton exposes subscription payment info
• Determine if order details show payment status

Add fields if applicable

If payment schedules are queried:

• Add balanceDue, totalBalance, due to fragment
• Display in order details
• Show overdue status

Documentation

• Document payment schedule fields
• Example for subscription order details
• Explain when payment schedule data appears

Priority

P2 - New fields for subscription/installment use cases