Invoices

Introduction

Invoices are usually a key part of B2B purchasing workflow. It’s typical for company buyers to pay with credit initially on an order (in BigCommerce, this means using the Check/Purchase Order payment method), then pay an invoice for that order at a later date.

We’ve already seen a glimpse of the Credit and Payment Terms configuration that are related to credit payment workflow. In this section, we’ll discuss invoices themselves.

The storefront-facing experience related to invoices only begins after an invoice has been created by the merchant. Therefore, the GraphQL storefront API does not expose any operations related to the creation, update, or deletion of invoices, only those related to viewing a company’s invoices and initiating payment for them.

Fetching Invoices

The current company’s invoices can be fetched with the invoices query.

Example query and response:

query GetInvoices {
    invoices {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                id
                invoiceNumber
                createdAt
                customerId
                dueDate
                status
                orderNumber
                purchaseOrderNumber
                details
                pendingPaymentCount
                originalBalance {
                    code
                    value
                }
                openBalance {
                    code
                    value
                }
            }
        }
    }
}

• invoices supports standard pagination arguments.
• Other available arguments to filter invoice results include invoiceNumber, orderNumber, purchaseOrderNumber, and status.
• Invoices can be filtered by creation or due date using the arguments beginDateAt, endDateAt, beginDueDateAt, and endDueDateAt. All of these arguments except an integer timestamp value.
• Results can also be filtered by one or more invoice ID using the argument idIn, which accepts a string value with a comma-separated list of invoice IDs. (For example, “5556677,5556678”)
• The customerId field actually contains the ID of the company.
• The status of an invoice will be 0 if the invoice is open (meaning no payment has been made), 1 if partial payment has been applied, and 2 if the invoice is fully paid. When the open balance of an invoice has been reduced to 0, the status will automatically be set to 2.
• details returns a complex object, but its GraphQL type does not allow more granular querying of the sub-fields. The details fields (header.billingAddress, details.shipments, etc) contain full information about the order that was invoiced.
• pendingPaymentCount relates to the payment records that have been recorded against the invoice (see next section). While the amounts of any payments applied to the invoice will be reflected in its open balance, any of those payments that are still in “Awaiting Processing” or “Processing” status will be reflected in pendingPaymentCount.
• openBalance.value will equal the original invoice balance minus all applied payments.

Fetching a Single Invoice

The invoice query can be used to fetch a single invoice using its ID.

This query returns the same GraphQL type as the nodes returned from invoices, so the same fields can be queried.

Example Request:

query GetInvoice(
    $invoiceId: Int!
) {
    invoice(
        invoiceId: $invoiceId
    ) {
        id
        invoiceNumber
        createdAt
        customerId
        dueDate
        ...
    }
}

Downloading Invoices

Invoice information is also available in the form of downloadable CSV exports or PDFs.

Downloading a CSV Export

The invoicesExport mutation can be used to export a CSV file containing one or more invoices.

Example mutation and response:

mutation InvoicesExport {
    invoicesExport{
        url
    }
}

The invoiceFilterData argument can be provided to filter the exported results.

Example mutation and variables:

mutation InvoicesExport(
    $beginDate: Int,
    $endDate: Int
) {
    invoicesExport(
        invoiceFilterData: {
            beginDateAt: $beginDate,
            endDateAt: $endDate
        }
    ) {
        url
    }
}

In addition to fields for filtering on invoice date, the invoiceFilterData also supports the fields invoiceNumber, orderNumber, status, and idIn. As with the invoices query, idIn accepts a comma-separated string.

Downloading a PDF

The invoicePdf mutation is intended only for a single invoice, returning a PDF download URL.

Example mutation and response:

mutation GetInvoicePdf(
    $invoiceId: Int!
) {
    invoicePdf(
        invoiceId: $invoiceId,
        isPayNow: true
    ) {
        url
    }
}

The isPayNow argument accepted by invoicePdf controls the appearance of a pay button in the final PDF. If isPayNow is TRUE, the PDF will include a “Pay Now” button that links the user to checkout for the invoice payment.

Initiating Invoice Checkout

Once an invoice has been created, company users need the ability to make payment on it from the storefront.

Similar to the case with creating an order from a quote, this can be done with the invoiceCreateBcCart mutation.

Example mutation, variables, and response:

mutation GetInvoiceCheckout(
    $invoiceId: Int!,
    $amount: String!,
    $currency: String!
) {
    invoiceCreateBcCart(
        bcCartData: {
            lineItems: [
                {
                    invoiceId: $invoiceId,
                    amount: $amount
                }
            ],
            currency: $currency,
            details: {}
        }
    ) {
        result {
            checkoutUrl
            cartId
        }
    }
}

• The details field of the bcCartData argument is required but should receive an empty object.
• A partial payment can be initiated by providing an amount less than the open balance of the invoice. Attempting to provide a value for amount greater than the open balance will result in a validation error.
• The cartId queried in the response is a BigCommerce cart identifier.

Redirecting a user to the checkoutUrl will initiate a BigCommerce checkout with the invoice payment loaded into the “cart.” The allowed payment methods you’ve configured in your store for invoice payment will be reflected in the checkout, and once the order is placed, the payment will be applied to the invoice.

Note that the bcCartData argument for invoiceCreateBcCart actually accepts an array of lineItems. This means that it’s possible to initiate a checkout for the payment of multiple invoices.

Example mutation and variables:

mutation GetInvoiceCheckout(
    $invoiceLines: [InvoiceLineItemsInputType]!,
    $currency: String!
) {
    invoiceCreateBcCart(
        bcCartData: {
            lineItems: $invoiceLines,
            currency: $currency,
            details: {}
        }
    ) {
        result {
            checkoutUrl
            cartId
        }
    }
}