Skip to main content
Use payment history to reconcile a subscription’s charges with your payment provider or accounting system. Authenticate with a project API access token that can read payments.

​
Query payment history

This query returns payments for one subscription, their original payment and retry attempts, and the associated invoice:
Example variables:
When hasNextPage is true, pass endCursor as after to retrieve the next page.

​
Follow retries

  • originalPayment returns the original payment, or the current payment itself when it is not a retry.
  • retriedPayment returns the original payment for a retry; it is null for an original payment.
  • Query retryAttempts on the original payment to get its attempts from oldest to newest.
  • paymentId is the payment provider’s reference, while id identifies the Firmhouse payment.
The original payment and its retries refer to the same invoice. Group records by originalPayment.id when reconciling a payment chain, rather than treating every retry as a separate invoice. Use each attempt’s status to distinguish successful charges from failed or pending attempts.

​
Read chargeback timestamps

paidAt remains available after an invoice is charged back. chargedBackAt records the most recent chargeback transition; it is not a full chargeback event history. Read invoiceStatus for the invoice’s current status and consult your payment provider for the chargeback reason. An invoice or timestamp can be null when it does not apply to the payment.

​
Read Shopify line attributes

Shopify invoice line items can include shopify_custom_attributes inside their metadata JSON. These are the originating Shopify order line’s custom attributes, useful for preserving external fulfillment or accounting references. For example:
Handle missing or empty metadata: existing invoices are not backfilled, and lines without Shopify custom attributes do not contain this key. These attributes provide context; they do not change product, price, or tax calculations.