Payments and Receipts

Introduction

The final key aspect of the B2B storefront purchasing experience is the ability to inspect a company’s invoice payments.

B2B Edition contains two related entities: payments and receipts. The “receipt” records attached to payments contain the most granular details about the payment transactions.

Fetching Payments

Fetch a list of the current company’s invoice payments with the invoicePayments query.

Example query and response:

query GetPayments {
    invoicePayments {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                id
                createdAt
                totalCode
                totalAmount
                payerName
                processingStatus
                companyId
                companyName
                paymentReceiptSet {
                    edges {
                        node {
                            id
                            createdAt
                            customerId
                            totalCode
                            totalAmount
                            payerName
                            paymentId
                            paymentType
                            receiptLineSet {
                                edges {
                                    node {
                                        id
                                        createdAt
                                        customerId
                                        receiptId
                                        paymentId
                                        invoiceId
                                        invoiceNumber
                                        amount
                                        paymentType
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

• invoicePayments supports standard pagination arguments, as do paymentReceiptSet and receiptLineSet, which are also standard cursor lists.
• Other supported filtering arguments include invoiceId, dateCreatedBeginAt, and dateCreatedEndAt. The date-related filter arguments accept a date string like “2025-01-01”.
• Note in the response above that a payment contains a paymentReceiptSet, while each payment receipt contains a receiptLineSet. In the above example, the first payment included only a single receipt line for a single invoice (0556679). The second payment in the results included two receipt lines, as payment was made against two different invoices (05556677 and 05556678).
• The payment records include basic transaction details like totalAmount, while the receipt and receipt line records include further details such as the paymentType. In the above example, the first payment in the results was an “offline” payment applied manually to an invoice, while the second payment was captured via credit card from a BigCommerce checkout and order, resulting in the paymentType”visa ending in 1111”.
• In the above example, note that in the second payment, the individual invoice amounts are queried in the receipt lines ($100 and$75), while the total payment amount of $175 is expressed in totalAmount on the payment record.
• The customerId field on receipt and receipt line records contains the company’s ID.
• The processingStatus of a payment will be 1 if the payment is “Awaiting Processing”, 2 for “Processing”, 3 for “Completed”, and 4 for “Refunded.” Recall that the processing status of each payment will affect the pendingPaymentCount of the associated invoices.

Note that while invoicePayments can be filtered on an invoice ID, the results returned will still include the full receipt details for the payments. Remember that a payment can potentially include multiple invoices, so filtering on an invoice ID is not a guarantee that the resulting payment details will be relevant only to that invoice.

For this reason, the most common use case for this query is when you want to present a storefront user with full details of their payment transactions, rather than payments by invoice.

Fetching a Single Payment

The invoicePayment query can be used to fetch a single payment using its ID. This query returns the same GraphQL type as the nodes returned from invoicePayments, so the same fields can be queried.

Example Request:

query GetPayment(
    $paymentId: Int!
) {
    invoicePayment(
        paymentId: $paymentId
    ) {
        id
        createdAt
        totalCode
        totalAmount
        ...
        paymentReceiptSet {
            edges {
                node {
                    id
                    createdAt
                    customerId
                    totalCode
                    totalAmount
                    ...
                    receiptLineSet {
                        edges {
                            node {
                                id
                                createdAt
                                customerId
                                receiptId
                                paymentId
                                invoiceId
                                ...
                            }
                        }
                    }
                }
            }
        }
    }
}

Fetching Receipt Lines

As mentioned above, payments can potentially include amounts applied to multiple invoices. In contexts where you want to present storefront users with the payment details relevant only to a specific invoice, it’s useful to be able to query receipt lines directly.

The allReceiptLines query can be used to fetch a list of receipt line records and can be filtered on a specific invoice ID. The results returned are of the same GraphQL type as the list items a receiptLineSet seen above, so the same fields can be queried.

Example query, variables, and response:

query GetReceiptLines(
    $invoiceId: String
) {
    allReceiptLines(
        invoiceId: $invoiceId
    ) {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                id
                createdAt
                customerId
                receiptId
                paymentId
                invoiceId
                invoiceNumber
                amount
                paymentStatus
                paymentType
            }
        }
    }
}

The above example relates to the previous example response for invoicePayments. Note that the single returned result was part of a payment that included receipt lines for two separate invoices. But since this allReceiptLines query is filtered on a specific invoice ID, only the relevant line is returned.

The paymentStatus field on a receipt line should match the processingStatus of its payment.

Fetching a Single Receipt Line

The receiptLine query will fetch the details of a single receipt line, using its ID. This returns the same GraphQL type as each node returned from allReceiptLines, so the same fields can be queried.

Example Request:

query GetReceiptLine(
    $id: Int!
) {
    receiptLine(
        id: $id
    ) {
        id
        createdAt
        customerId
        receiptId
        paymentId
        invoiceId
        invoiceNumber
        amount
        paymentStatus
        paymentType
    }
}

Fetching Receipts

There are available receipts and receipt queries for fetching receipt records specifically. However, these queries are generally redundant with fetching payments, since there is almost always a single receipt associated with a payment, receipt details can already be queried directly under payments, and receipts can’t be filtered on the same arguments (like invoice ID). Directly querying payments or receipt lines should serve the various use cases of your storefront applications.