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

# List Invoices

GET https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices

get invoices

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/b2b/management/invoice-management/invoice/get-invoices

## Authentication

- `X-Auth-Token` header (required) — | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts). | For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
- `X-Store-Hash` header (required) — | Header | Argument | Description | |:-------|:---------|:------------| | `X-Store-Hash` | `store_hash` | The unique store hash associated with a BigCommerce store that has B2B Edition enabled. |

## Request

### Query parameters

- `offset` (double, optional) — The number of results to skip before returning results.
- `limit` (double, optional) — The number of results to return per page.
- `orderBy` (enum, optional) — "DESC" or "ASC"
  - Allowed values: `DESC`, `ASC`
- `sortBy` (enum, optional) — Sort by the field value
  - Allowed values: `invoiceNumber`, `createdAt`, `customerId`, `externalCustomerId`, `dueDate`, `updatedAt`, `isPendingPayment`, `openBalance`, `originalBalance`, `status`
- `searchBy` (enum, optional) — Filter by a field
  - Allowed values: `invoiceNumber`, `type`, `orderNumber`, `purchaseOrderNumber`, `customerId`, `externalCustomerId`
- `q` (string, optional) — You can perform keyword queries on fields corresponding to the value of "searchBy" or, if "searchBy" is empty, on all fields supported by "searchBy".
- `customerName` (string, optional) — Query by invoice B2B Edition company name
- `customerId` (string, optional) — Query by invoice B2B Edition company ID
- `status` (enum, optional) — Query by invoice status
  - Allowed values: `0`, `1`, `2`
- `beginDateAt` (string, optional) — Query by the created timestamp, along with the "endDateAt" parameter
- `endDateAt` (string, optional) — Query by the created timestamp, along with the with the "beginDateAt" parameter
- `externalId[]` (list of double, optional) — Query by the invoice external ID
- `isIncludeExtraFields` (enum, optional) — Determine if extra fields should show in the response
  - Allowed values: `0`, `1`
- `channelIds` (list of double, optional) — BigCommerce Channel IDs

## Response

### 200

OK

- `code` (double, optional)
- `data` (list of InvoicesGetResponsesContentApplicationJsonSchemaDataItems, optional)
- `meta` (InvoicesGetResponsesContentApplicationJsonSchemaMeta, optional)

## Types

### InvoicesGetResponsesContentApplicationJsonSchemaDataItems

Extra Field Values

- `customerId` (string, required) — B2B Edition Company ID
- `originalBalance` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsOriginalBalance, required) — Origin balance
- `openBalance` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsOpenBalance, required) — Invoice open balance
- `id` (double, optional) — Invoice ID
- `externalCustomerId` (string, optional) — ID of a company associated with a third party
- `externalId` (string, optional) — The ID of the invoice associated with the third party
- `invoiceNumber` (string, optional) — Invoice no.
- `type` (string, optional) — Invoice Type
- `dueDate` (double, optional) — Invoice due date
- `status` (double, optional) — Invoice status. If the balance is less than or equal to 0, then it will automatically update to status "2".
- `orderNumber` (string, optional) — BigCommerce order ID
- `purchaseOrderNumber` (string, optional) — PO no.
- `details` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetails, optional) — Invoice details
- `isPendingPayment` (double, optional)
- `source` (enum, optional) — Source of invoice 0 for B2B Edition 1 for External
  - Allowed values: `0`, `1`
- `customerName` (string, optional) — BigCommerce customer group name
- `createdAt` (string, optional) — Invoice creation time
- `updatedAt` (string, optional) — Invoice last updated time
- `channelId` (string, optional) — BigCommerce channel id
- `channelName` (string, optional) — Store Channel Name
- `termsConditions` (string, optional) — Terms & Conditions. Visible on the default Invoice PDF.
- `extraFields` (list of InvoicesGetResponsesContentApplicationJsonSchemaDataItemsExtraFieldsItems, optional)

### InvoicesGetResponsesContentApplicationJsonSchemaMeta

- `message` (string, optional)
- `pagination` (InvoicesGetResponsesContentApplicationJsonSchemaMetaPagination, optional)

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsOriginalBalance

Origin balance

- `code` (string, required) — currency code
- `value` (string, required) — amount

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsOpenBalance

Invoice open balance

- `code` (string, required) — currency code
- `value` (string, required) — amount

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetails

Invoice details

- `type` (string, required) — Invoice details type
- `header` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeader, required)
- `details` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetails, optional)

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsExtraFieldsItems

- `fieldName` (string, required) — Field name that config in you store
- `fieldValue` (string, required) — Value of the extra field.

### InvoicesGetResponsesContentApplicationJsonSchemaMetaPagination

- `totalCount` (integer, optional)
- `limit` (integer, optional)
- `offset` (integer, optional)

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeader

- `costLines` (list of InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderCostLinesItems, required) — Invoice cost information
- `orderDate` (double, required) — Invoice order creation time
- `billingAddress` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderBillingAddress, required) — Invoice billing address
- `shippingAddresses` (list of InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderShippingAddressesItems, required) — Invoice shipping addresses
- `customerFields` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderCustomerFields, optional) — User-defined additional fields

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetails

- `lineItems` (list of InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsLineItemsItems, required) — Invoice Product Information
- `shipments` (list of InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsShipmentsItems, optional) — Invoice shipments information

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderCostLinesItems

- `amount` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderCostLinesItemsAmount, required) — cost amount
- `description` (string, required) — cost description

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderBillingAddress

Invoice billing address

- `city` (string, required)
- `state` (string, required)
- `country` (string, required)
- `street1` (string, required)
- `street2` (string, required)
- `zipCode` (string, required)
- `lastName` (string, required)
- `firstName` (string, required)
- `customFields` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderBillingAddressCustomFields, optional)

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderShippingAddressesItems

- `city` (string, required)
- `state` (string, required)
- `country` (string, required)
- `street1` (string, required)
- `street2` (string, required)
- `zipCode` (string, required)
- `lastName` (string, required)
- `firstName` (string, required)
- `customFields` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderShippingAddressesItemsCustomFields, optional)

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderCustomerFields

User-defined additional fields

- `key` (string, optional) — custom field key
- `value` (string, optional) — custom field value

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsLineItemsItems

- `sku` (string, required) — Product sku
- `type` (string, required) — product type
- `comments` (string, required)
- `quantity` (string, required) — product qyantity
- `unitPrice` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsLineItemsItemsUnitPrice, required) — product unit price
- `description` (string, required) — product description or product name
- `unitDiscount` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsLineItemsItemsUnitDiscount, required) — product unit discount
- `customFields` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsLineItemsItemsCustomFields, optional)

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsShipmentsItems

- `addressIndex` (string, required) — address ID
- `shipDate` (string, required) — Time of shipment
- `shipVia` (string, required)
- `trackingNumber` (string, required) — tracking number
- `comments` (string, required) — comments
- `customFields` (InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsShipmentsItemsCustomFields, optional)

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderCostLinesItemsAmount

cost amount

- `code` (string, required)
- `value` (string, required)

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderBillingAddressCustomFields

- `key` (string, optional) — custom field key
- `value` (string, optional) — custom field value

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsHeaderShippingAddressesItemsCustomFields

- `key` (string, optional) — custom field key
- `value` (string, optional) — custom field value

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsLineItemsItemsUnitPrice

product unit price

- `code` (string, required) — currency code
- `value` (string, required) — amount

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsLineItemsItemsUnitDiscount

product unit discount

- `code` (string, required) — currency code
- `value` (string, required) — amount

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsLineItemsItemsCustomFields

- `key` (string, optional) — custom field key
- `value` (string, optional) — custom field value

### InvoicesGetResponsesContentApplicationJsonSchemaDataItemsDetailsDetailsShipmentsItemsCustomFields

- `key` (string, optional) — custom field key
- `value` (string, optional) — custom field value

## Examples

**Response**

```json
{
  "code": 1.1,
  "data": [
    {
      "customerId": "string",
      "originalBalance": {
        "code": "string",
        "value": "string"
      },
      "openBalance": {
        "code": "string",
        "value": "string"
      },
      "id": 1.1,
      "externalCustomerId": "string",
      "externalId": "string",
      "invoiceNumber": "string",
      "type": "string",
      "dueDate": 1.1,
      "status": 1.1,
      "orderNumber": "string",
      "purchaseOrderNumber": "string",
      "details": {
        "type": "string",
        "header": {
          "costLines": [
            {
              "amount": {
                "code": "string",
                "value": "string"
              },
              "description": "string"
            }
          ],
          "orderDate": 1.1,
          "billingAddress": {
            "city": "string",
            "state": "string",
            "country": "string",
            "street1": "string",
            "street2": "string",
            "zipCode": "string",
            "lastName": "string",
            "firstName": "string",
            "customFields": {
              "key": "string",
              "value": "string"
            }
          },
          "shippingAddresses": [
            {
              "city": "string",
              "state": "string",
              "country": "string",
              "street1": "string",
              "street2": "string",
              "zipCode": "string",
              "lastName": "string",
              "firstName": "string",
              "customFields": {
                "key": "string",
                "value": "string"
              }
            }
          ],
          "customerFields": {
            "key": "string",
            "value": "string"
          }
        },
        "details": {
          "lineItems": [
            {
              "sku": "string",
              "type": "string",
              "comments": "string",
              "quantity": "string",
              "unitPrice": {
                "code": "USA",
                "value": "string"
              },
              "description": "string",
              "unitDiscount": {
                "code": "string",
                "value": "string"
              },
              "customFields": {
                "key": "string",
                "value": "string"
              }
            }
          ],
          "shipments": [
            {
              "addressIndex": "string",
              "shipDate": "string",
              "shipVia": "string",
              "trackingNumber": "string",
              "comments": "string",
              "customFields": {
                "key": "string",
                "value": "string"
              }
            }
          ]
        }
      },
      "isPendingPayment": 1.1,
      "source": 0,
      "customerName": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "channelId": "string",
      "channelName": "string",
      "termsConditions": "string",
      "extraFields": [
        {
          "fieldName": "string",
          "fieldValue": "string"
        }
      ]
    }
  ],
  "meta": {
    "message": "string",
    "pagination": {
      "totalCount": 1,
      "limit": 1,
      "offset": 1
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices"

querystring = {"orderBy":"DESC","searchBy":"invoiceNumber","sortBy":"invoiceNumber","status":"1"}

headers = {"X-Auth-Token": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices?orderBy=DESC&searchBy=invoiceNumber&sortBy=invoiceNumber&status=1';
const options = {method: 'GET', headers: {'X-Auth-Token': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices?orderBy=DESC&searchBy=invoiceNumber&sortBy=invoiceNumber&status=1"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Auth-Token", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices?orderBy=DESC&searchBy=invoiceNumber&sortBy=invoiceNumber&status=1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Auth-Token"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices?orderBy=DESC&searchBy=invoiceNumber&sortBy=invoiceNumber&status=1")
  .header("X-Auth-Token", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices?orderBy=DESC&searchBy=invoiceNumber&sortBy=invoiceNumber&status=1', [
  'headers' => [
    'X-Auth-Token' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices?orderBy=DESC&searchBy=invoiceNumber&sortBy=invoiceNumber&status=1");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Auth-Token", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["X-Auth-Token": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices?orderBy=DESC&searchBy=invoiceNumber&sortBy=invoiceNumber&status=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```