***

title: Billing
description: >-
Manage and retrieve billing-related data including invoices, transactions, and
transaction fees
last-updated: 'February 24, 2026'
---------------------------------

The ShipBob Billing API provides endpoints to manage and retrieve billing-related data, including invoices, transactions, and transaction fees. All requests require a Personal Access Token (PAT) with the `billing_read` scope. This guide details the four available endpoints, including sample requests and responses.

## Authentication

To access the Billing API endpoints, you must use a valid Personal Access Token (PAT) with the `billing_read` scope. If you encounter access issues (e.g., `403 Forbidden` errors), follow these steps:

1. **Verify `billing_read` Scope**:
   * Make a request to the `GET /2025-07/channels` endpoint to confirm your PAT includes the `billing_read` scope.
   * **Sample Request**:
     ```bash
     curl -X GET "https://api.shipbob.com/2025-07/channels" \
     -H "Authorization: Bearer <your_PAT>" \
     -H "Content-Type: application/json"
     ```
   * If the response indicates the `billing_read` scope is missing, generate a new PAT.

2. **Generate a New PAT**:
   * Log in to the ShipBob Dashboard and navigate to **Settings > API > Personal Access Tokens**.
   * Create a new PAT with the `billing_read` scope enabled.
   * Update your API requests with the new PAT.

***

## Get Invoices

Retrieves a list of invoices within a specified date range.

**Endpoint**\
`GET /2025-07/invoices`

[API Reference ↗](https://developer.shipbob.com/api/billing/get-invoices)

**Query Parameters**

| Parameter  | Type   | Required | Description                                          |
| ---------- | ------ | -------- | ---------------------------------------------------- |
| `FromDate` | string | Yes      | Start date (YYYY-MM-DD)                              |
| `ToDate`   | string | Yes      | End date (YYYY-MM-DD)                                |
| `Page`     | number | No       | Page number for pagination (default: 1)              |
| `PageSize` | number | No       | Number of invoices per page (default: 100, max: 100) |

**Headers**

| Header          | Value               |
| --------------- | ------------------- |
| `Authorization` | `Bearer <your_PAT>` |
| `Content-Type`  | `application/json`  |

**Sample Request**

```bash
curl -X GET "https://api.shipbob.com/2025-07/invoices?FromDate=2025-09-01&ToDate=2025-10-23&Page=1&PageSize=50" \
-H "Authorization: Bearer <your_PAT>" \
-H "Content-Type: application/json"
```

**Sample Response**

```json expandable
{
  "items": [
    {
      "invoice_id": 8405612,
      "invoice_date": "2025-10-14",
      "invoice_type": "Payment",
      "amount": -7.14,
      "currency_code": "USD",
      "running_balance": 0
    },
    {
      "invoice_id": 8405608,
      "invoice_date": "2025-10-14",
      "invoice_type": "CreditCardProcessingFee",
      "amount": 0.21,
      "currency_code": "USD",
      "running_balance": 7.14
    },
    {
      "invoice_id": 8404298,
      "invoice_date": "2025-10-14",
      "invoice_type": "Shipping",
      "amount": 6.93,
      "currency_code": "USD",
      "running_balance": 6.93
    }
  ]
}
```

***

## Search Transactions

Queries transactions based on specified criteria, such as date range or transaction type.

**Endpoint**\
`POST /2025-07/transactions:query`

[API Reference ↗](https://developer.shipbob.com/api/billing/search-transactions)

**Headers**

| Header          | Value               |
| --------------- | ------------------- |
| `Authorization` | `Bearer <your_PAT>` |
| `Content-Type`  | `application/json`  |

**Request Body**

| Field               | Type   | Required | Description                                               |
| ------------------- | ------ | -------- | --------------------------------------------------------- |
| `from_date`         | string | Yes      | Start date (YYYY-MM-DD)                                   |
| `to_date`           | string | Yes      | End date (YYYY-MM-DD)                                     |
| `page`              | number | No       | Page number (default: 1)                                  |
| `page_size`         | number | No       | Transactions per page (default: 100, max: 100)            |
| `transaction_types` | array  | No       | Filter by transaction types (e.g., \["Charge", "Refund"]) |
| `invoice_statuses`  | array  | No       | Filter by invoice status (e.g., \[true, false])           |

**Sample Request**

```bash
curl -X POST "https://api.shipbob.com/2025-07/transactions:query" \
-H "Authorization: Bearer <your_PAT>" \
-H "Content-Type: application/json" \
-d '{
  "from_date": "2025-10-01",
  "to_date": "2025-10-23",
  "page": 1,
  "page_size": 50,
  "transaction_types": ["Charge"],
  "invoice_statuses": [true]
}'
```

**Sample Response**

```json expandable
{
  "items": [
    {
      "transaction_id": "01K7FHRK39R603254DSCD0YXR2",
      "amount": 6.93,
      "currency_code": "USD",
      "charge_date": "2025-10-13",
      "invoiced_status": true,
      "invoice_date": "2025-10-14",
      "transaction_fee": "Shipping",
      "invoice_id": 8404298,
      "invoice_type": "Shipping",
      "reference_id": "305406896",
      "reference_type": "Shipment",
      "transaction_type": "Charge",
      "fulfillment_center": "ShipBob Test FC (Innovation Center)",
      "taxes": [],
      "additional_details": {
        "TrackingId": "9261290318421111944909",
        "Comment": ""
      }
    },
    {
      "transaction_id": "01K7DWXJ7QD7X8XSJB9XG4K8QJ",
      "amount": 1.8245,
      "currency_code": "USD",
      "charge_date": "2025-10-13",
      "invoiced_status": true,
      "invoice_date": "2025-10-13",
      "transaction_fee": "WMS - Fuel Surcharge",
      "invoice_id": 8399540,
      "invoice_type": "AdditionalFee",
      "reference_id": "304771824",
      "reference_type": "Shipment",
      "transaction_type": "Charge",
      "fulfillment_center": "ShipBob Test FC (M+)",
      "taxes": [],
      "additional_details": {
        "TrackingId": "",
        "Comment": "$1.8245 USD amount calculated (@20.25% of $9.01 cost). A discount of $0 was applied."
      }
    }
  ]
}
```

***

## Get Transactions by Invoice ID

Retrieves all transactions associated with a specific invoice ID.

**Endpoint**\
`GET /2025-07/invoices/{invoiceId}/transactions`

[API Reference ↗](/api/billing/get-transactions-by-invoice-id)

**Path Parameters**

| Parameter   | Type   | Required | Description           |
| ----------- | ------ | -------- | --------------------- |
| `invoiceId` | number | Yes      | The ID of the invoice |

**Query Parameters**

| Parameter  | Type   | Required | Description                                              |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| `Page`     | number | No       | Page number for pagination (default: 1)                  |
| `PageSize` | number | No       | Number of transactions per page (default: 100, max: 100) |

**Headers**

| Header          | Value               |
| --------------- | ------------------- |
| `Authorization` | `Bearer <your_PAT>` |
| `Content-Type`  | `application/json`  |

**Sample Request**

```bash
curl -X GET "https://api.shipbob.com/2025-07/invoices/8404298/transactions?Page=1&PageSize=50" \
-H "Authorization: Bearer <your_PAT>" \
-H "Content-Type: application/json"
```

**Sample Response**

```json expandable
{
  "items": [
    {
      "transaction_id": "01K7FHRK39R603254DSCD0YXR2",
      "amount": 6.93,
      "currency_code": "USD",
      "charge_date": "2025-10-13",
      "invoiced_status": true,
      "invoice_date": "2025-10-14",
      "transaction_fee": "Shipping",
      "invoice_id": 8404298,
      "invoice_type": "Shipping",
      "reference_id": "305406896",
      "reference_type": "Shipment",
      "transaction_type": "Charge",
      "fulfillment_center": "ShipBob Test FC (Innovation Center)",
      "taxes": [],
      "additional_details": {
        "TrackingId": "9261290318421111944909",
        "Comment": ""
      }
    }
  ]
}
```

***

## Get Transaction Fees

Retrieves a list of available transaction fee types.

**Endpoint**\
`GET /2025-07/transaction-fees`

[API Reference ↗](https://developer.shipbob.com/api/billing/get-transaction-fees)

**Headers**

| Header          | Value               |
| --------------- | ------------------- |
| `Authorization` | `Bearer <your_PAT>` |
| `Content-Type`  | `application/json`  |

**Sample Request**

```bash
curl -X GET "https://api.shipbob.com/2025-07/transaction-fees" \
-H "Authorization: Bearer <your_PAT>" \
-H "Content-Type: application/json"
```

**Sample Response**

```json expandable
{
  "items": [
    {
      "fee_type": "Shipping",
      "description": "Cost associated with shipping a package"
    },
    {
      "fee_type": "WMS - Fuel Surcharge",
      "description": "Fuel surcharge applied to shipping"
    },
    {
      "fee_type": "Delivery Area Surcharge",
      "description": "Additional fee for deliveries to specific areas"
    },
    {
      "fee_type": "CreditCardProcessingFee",
      "description": "Fee for processing credit card payments"
    },
    {
      "fee_type": "AdditionalFee",
      "description": "Miscellaneous additional fees"
    }
  ]
}
```

***

## Notes

* **Date Format**: All dates must be in `YYYY-MM-DD` format.
* **Pagination**: Endpoints that support pagination use `Page` and `PageSize` parameters (default: 100, max: 100).
* **Scopes**: The `billing_read` scope is required for all endpoints. Requests without it will fail with an authorization error.
* **API Specification**: For full details, refer to the [ShipBob API Specification](https://marketplaceapi.shipbob.com/docs/2025-07.json).
* **Support**: For issues, contact ShipBob support via the dashboard or review the API documentation for updates.