> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Invoices Plan: B2B Developer Lesson 14 of 18 ยท 30 min ## 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. > **Info** > > The `invoices` query is available when the user associated with the Bearer token has the Senior Buyer role or higher, or a custom role with the "Invoices - View" permission. ### Example query and response: #### Query ```graphql showLineNumbers={false} 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 } } } } } ``` #### Response ```json showLineNumbers={false} { "data": { "invoices": { "pageInfo": { "hasNextPage": true, "hasPreviousPage": false, "startCursor": "YXJy...", "endCursor": "YXJy..." }, "totalCount": 12, "edges": [ { "node": { "id": "5556677", "invoiceNumber": "05556677", "createdAt": 1724276491, "customerId": "1112233", "dueDate": 1726868491, "status": 1, "orderNumber": "120", "purchaseOrderNumber": "12345", "details": { "type": "StandardInvoiceDetails", "header": { "cost_lines": [ { "amount": { "code": "USD", "value": "341.0000" }, "description": "Subtotal" }, ... ], "order_date": 1724273249, "billing_address": { ... }, "customer_fields": {}, "shipping_addresses": [ { ... } ] }, "details": { "shipments": [ ... ], "line_items": [ ... ] } }, "pendingPaymentCount": 0, "originalBalance": { "code": "USD", "value": "325.5200" }, "openBalance": { "code": "USD", "value": "325.5200" } } }, ... ] } } } ``` * `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. > **Info** > > The `invoice` query is available when the user associated with the Bearer token has the Senior Buyer role or higher, or a custom role with the "Invoices - View" permission. This query returns the same GraphQL type as the nodes returned from `invoices`, so the same fields can be queried. ### Example Request: ```graphql showLineNumbers={false} 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. > **Info** > > Both of the following mutations - `invoicesExport` and `invoicePdf`- are available when the user associated with the Bearer token has the Senior Buyer role or higher, or a custom role with the "Invoices - View" permission. ### 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 ```graphql showLineNumbers={false} mutation InvoicesExport { invoicesExport{ url } } ``` #### Response ```json showLineNumbers={false} { "data": { "invoicesExport": { "url": "https://s3-us-west-2.amazonaws.com/bundleb2b-v3.0-invoice-prod/invoice-export-pki...-1726003486.csv" } } } ``` The `invoiceFilterData` argument can be provided to filter the exported results. #### Example mutation and variables: #### Mutation ```graphql showLineNumbers={false} mutation InvoicesExport( $beginDate: Int, $endDate: Int ) { invoicesExport( invoiceFilterData: { beginDateAt: $beginDate, endDateAt: $endDate } ) { url } } ``` #### Variables ```json showLineNumbers={false} { "beginDate": 1704088800, "endDate": 1735711199 } ``` 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 ```graphql showLineNumbers={false} mutation GetInvoicePdf( $invoiceId: Int! ) { invoicePdf( invoiceId: $invoiceId, isPayNow: true ) { url } } ``` #### Response ```json showLineNumbers={false} { "data": { "invoicePdf": { "url": "https://s3-us-west-2.amazonaws.com/bundleb2b-v2.0-quote-prod/My_Store_05556677_ec01cb3a-....pdf" } } } ``` 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. > **Info** > > The `invoiceCreateBcCart` mutation is available when the user associated with the Bearer token has the Admin role or a custom role with the "Invoices - Pay invoices" permission. #### Example mutation, variables, and response: #### Mutation ```graphql showLineNumbers={false} mutation GetInvoiceCheckout( $invoiceId: Int!, $amount: String!, $currency: String! ) { invoiceCreateBcCart( bcCartData: { lineItems: [ { invoiceId: $invoiceId, amount: $amount } ], currency: $currency, details: {} } ) { result { checkoutUrl cartId } } } ``` #### Variables ```json showLineNumbers={false} { "invoiceId": 5556677, "amount": "325.5200", "currency": "USD" } ``` #### Response ```json showLineNumbers={false} { "data": { "invoiceCreateBcCart": { "result": { "checkoutUrl": "https://mystore.com/cart.php?...", "cartId": "550a97..." } } } } ``` * 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 ```graphql showLineNumbers={false} mutation GetInvoiceCheckout( $invoiceLines: [InvoiceLineItemsInputType]!, $currency: String! ) { invoiceCreateBcCart( bcCartData: { lineItems: $invoiceLines, currency: $currency, details: {} } ) { result { checkoutUrl cartId } } } ``` #### Variables ```json showLineNumbers={false} { "invoiceLines": [ { "invoiceId": 5556677, "amount": "100.0000" }, { "invoiceId": 5556678, "amount": "75.0000" } ], "currency": "USD" } ``` > **Info** > > It is possible to utilize the BigCommerce REST Management API to manually construct a cart with the "Invoice Payment" product installed by B2B Edition with the proper modifier option, but this is not an officially supported workflow.