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 invoice due dates and overdue invoices

Request dueDate on an invoice to read its stored payment due date as an ISO date, such as 2026-11-02. It is null when no date was assigned, including invoices finalized while payment terms were disabled. Changing the project’s payment term does not recalculate existing stored dates. Do not substitute the current payment term for a missing date. Use outstandingInvoices(overdue: true) to retrieve only outstanding invoices whose stored due date is before today in Firmhouse’s time zone (Europe/Amsterdam). Invoices due today, in the future, or without a stored date are excluded. Omitting overdue or passing false leaves the usual outstanding-invoice results unchanged.
The exclusion flags in this example are optional. Overdue filtering alone does not exclude invoices with pending status, uncollectible invoices, or invoices already in a collection case. Existing date, subscription, status, and payment-type filters still apply. Follow pageInfo.endCursor while hasNextPage is true.

​
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.