*** title: Billing description: Manage and retrieve billing-related data including invoices, transactions, and transaction fees last-updated: February 28, 2026 --------------------- For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://developer.shipbob.com/guides/llms.txt. For full documentation content, see https://developer.shipbob.com/guides/llms-full.txt. 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 /2026-01/channels` endpoint to confirm your PAT includes the `billing_read` scope. * **Sample Request**: ```bash curl -X GET "https://api.shipbob.com/2026-01/channels" \ -H "Authorization: Bearer " \ -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 /2026-01/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 ` | | `Content-Type` | `application/json` | **Sample Request** ```bash curl -X GET "https://api.shipbob.com/2026-01/invoices?FromDate=2025-09-01&ToDate=2025-10-23&Page=1&PageSize=50" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` **Sample Response** ```json { "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 /2026-01/transactions:query` [API Reference ↗](https://developer.shipbob.com/api/billing/search-transactions) **Headers** | Header | Value | | --------------- | ------------------- | | `Authorization` | `Bearer ` | | `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/2026-01/transactions:query" \ -H "Authorization: Bearer " \ -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 { "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 Fees for a Specific Shipment To retrieve all charges associated with a specific ShipBob shipment, make a `POST` request to `/2026-01/transactions:query` and filter by the shipment's `reference_id`. **Endpoint**\ `POST /2026-01/transactions:query` [API Reference ↗](https://developer.shipbob.com/api/billing/search-transactions) Some fees are not immediately available via the API after a label is generated in ShipBob. Depending on the fee type, it may take up to 6 hours before the fee data becomes available through the API. **Headers** | Header | Value | | --------------- | ------------------- | | `Authorization` | `Bearer ` | | `Content-Type` | `application/json` | **Request Body** | Field | Type | Required | Description | | --------------- | ----- | -------- | ----------------------------------------------------- | | `reference_ids` | array | Yes | One or more ShipBob shipment IDs to retrieve fees for | **Sample Request** ```bash curl -X POST https://api.shipbob.com/2026-01/transactions:query \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "reference_ids": [ "219384756" ] }' ``` **Sample Response** ```json { "items": [ { "transaction_id": "01MBX3RQNFW2K6P8TYUV5HCSD4", "amount": 4.96, "currency_code": "USD", "charge_date": "2026-02-15", "invoiced_status": false, "invoice_date": null, "transaction_fee": "B2B - Each Pick Fee", "invoice_id": null, "invoice_type": null, "reference_id": "219384756", "reference_type": "Shipment", "transaction_type": "Charge", "fulfillment_center": "SB Chicago (IL)", "taxes": [], "additional_details": { "TrackingId": "", "Comment": "PO Number: WXR4821T - EachPickFee - $0.31 per each" } }, { "transaction_id": "01MBX3RQNMJ7H9ZWQCF2VDKG8N", "amount": 1.75, "currency_code": "USD", "charge_date": "2026-02-15", "invoiced_status": false, "invoice_date": null, "transaction_fee": "B2B - Label Fee", "invoice_id": null, "invoice_type": null, "reference_id": "219384756", "reference_type": "Shipment", "transaction_type": "Charge", "fulfillment_center": "SB Chicago (IL)", "taxes": [], "additional_details": { "TrackingId": "", "Comment": "PO Number: WXR4821T - B2BLabelFee - $0.25 per label" } }, { "transaction_id": "01MB7KPZXTCW3N6QE9YSMJRVA2", "amount": 21.45, "currency_code": "USD", "charge_date": "2026-02-13", "invoiced_status": false, "invoice_date": null, "transaction_fee": "Shipping", "invoice_id": null, "invoice_type": null, "reference_id": "219384756", "reference_type": "Shipment", "transaction_type": "Charge", "fulfillment_center": "SB Chicago (IL)", "taxes": [], "additional_details": { "TrackingId": "784512936048", "Comment": "" } } ] } ``` You can pass multiple shipment IDs in the `reference_ids` array to retrieve fees for several shipments in a single request. Each transaction in the response includes `transaction_fee` (the fee type), `amount` , `charge_date` , and `additional_details` for line-item context like PO numbers and per-unit rates. *** ## Get Transactions by Invoice ID Retrieves all transactions associated with a specific invoice ID. **Endpoint**\ `GET /2026-01/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 ` | | `Content-Type` | `application/json` | **Sample Request** ```bash curl -X GET "https://api.shipbob.com/2026-01/invoices/8404298/transactions?Page=1&PageSize=50" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` **Sample Response** ```json { "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 /2026-01/transaction-fees` [API Reference ↗](https://developer.shipbob.com/api/billing/get-transaction-fees) **Headers** | Header | Value | | --------------- | ------------------- | | `Authorization` | `Bearer ` | | `Content-Type` | `application/json` | **Sample Request** ```bash curl -X GET "https://api.shipbob.com/2026-01/transaction-fees" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` **Sample Response** ```json { "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/2026-01.json). * **Support**: For issues, contact ShipBob support via the dashboard or review the API documentation for updates.