For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DocumentationAPI Reference
DocumentationAPI Reference
  • Get Started
    • Introduction
    • Quickstart
    • Authentication
    • Rate Limit
    • Webhooks
  • Integration Guides
    • Overview
    • Tracking
    • Receiving
    • Returns
    • Billing
  • Other
    • Concepts
    • Status Reference
    • Errors
    • FAQ
LogoLogo
On this page
  • Authentication
  • Get Invoices
  • Search Transactions
  • Get Fees for a Specific Shipment
  • Get Transactions by Invoice ID
  • Get Transaction Fees
  • Notes
Integration Guides

Billing

||View as Markdown|
Was this page helpful?

Last updated February 28, 2026

Previous

Returns

Next

Concepts

Built with

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: 
      $curl -X GET "https://api.shipbob.com/2026-01/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 /2026-01/invoices

API Reference ↗

Query Parameters

ParameterTypeRequiredDescription
FromDatestringYesStart date (YYYY-MM-DD)
ToDatestringYesEnd date (YYYY-MM-DD)
PagenumberNoPage number for pagination (default: 1)
PageSizenumberNoNumber of invoices per page (default: 100, max: 100)

Headers

HeaderValue
AuthorizationBearer <your_PAT>
Content-Typeapplication/json

Sample Request

$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 <your_PAT>" \
>-H "Content-Type: application/json"

Sample Response

1{
2  "items": [
3    {
4      "invoice_id": 8405612,
5      "invoice_date": "2025-10-14",
6      "invoice_type": "Payment",
7      "amount": -7.14,
8      "currency_code": "USD",
9      "running_balance": 0
10    },
11    {
12      "invoice_id": 8405608,
13      "invoice_date": "2025-10-14",
14      "invoice_type": "CreditCardProcessingFee",
15      "amount": 0.21,
16      "currency_code": "USD",
17      "running_balance": 7.14
18    },
19    {
20      "invoice_id": 8404298,
21      "invoice_date": "2025-10-14",
22      "invoice_type": "Shipping",
23      "amount": 6.93,
24      "currency_code": "USD",
25      "running_balance": 6.93
26    }
27  ]
28}

Search Transactions

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

Endpoint
POST /2026-01/transactions:query

API Reference ↗

Headers

HeaderValue
AuthorizationBearer <your_PAT>
Content-Typeapplication/json

Request Body

FieldTypeRequiredDescription
from_datestringYesStart date (YYYY-MM-DD)
to_datestringYesEnd date (YYYY-MM-DD)
pagenumberNoPage number (default: 1)
page_sizenumberNoTransactions per page (default: 100, max: 100)
transaction_typesarrayNoFilter by transaction types (e.g., [“Charge”, “Refund”])
invoice_statusesarrayNoFilter by invoice status (e.g., [true, false])

Sample Request

$curl -X POST "https://api.shipbob.com/2026-01/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

1{
2  "items": [
3    {
4      "transaction_id": "01K7FHRK39R603254DSCD0YXR2",
5      "amount": 6.93,
6      "currency_code": "USD",
7      "charge_date": "2025-10-13",
8      "invoiced_status": true,
9      "invoice_date": "2025-10-14",
10      "transaction_fee": "Shipping",
11      "invoice_id": 8404298,
12      "invoice_type": "Shipping",
13      "reference_id": "305406896",
14      "reference_type": "Shipment",
15      "transaction_type": "Charge",
16      "fulfillment_center": "ShipBob Test FC (Innovation Center)",
17      "taxes": [],
18      "additional_details": {
19        "TrackingId": "9261290318421111944909",
20        "Comment": ""
21      }
22    },
23    {
24      "transaction_id": "01K7DWXJ7QD7X8XSJB9XG4K8QJ",
25      "amount": 1.8245,
26      "currency_code": "USD",
27      "charge_date": "2025-10-13",
28      "invoiced_status": true,
29      "invoice_date": "2025-10-13",
30      "transaction_fee": "WMS - Fuel Surcharge",
31      "invoice_id": 8399540,
32      "invoice_type": "AdditionalFee",
33      "reference_id": "304771824",
34      "reference_type": "Shipment",
35      "transaction_type": "Charge",
36      "fulfillment_center": "ShipBob Test FC (M+)",
37      "taxes": [],
38      "additional_details": {
39        "TrackingId": "",
40        "Comment": "$1.8245 USD amount calculated (@20.25% of $9.01 cost). A discount of $0 was applied."
41      }
42    }
43  ]
44}

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 ↗

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

HeaderValue
AuthorizationBearer <your_PAT>
Content-Typeapplication/json

Request Body

FieldTypeRequiredDescription
reference_idsarrayYesOne or more ShipBob shipment IDs to retrieve fees for

Sample Request

$curl -X POST https://api.shipbob.com/2026-01/transactions:query \
>     -H "Authorization: Bearer <your_PAT>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "reference_ids": [
>    "219384756"
>  ]
>}'

Sample Response

1{
2  "items": [
3    {
4      "transaction_id": "01MBX3RQNFW2K6P8TYUV5HCSD4",
5      "amount": 4.96,
6      "currency_code": "USD",
7      "charge_date": "2026-02-15",
8      "invoiced_status": false,
9      "invoice_date": null,
10      "transaction_fee": "B2B - Each Pick Fee",
11      "invoice_id": null,
12      "invoice_type": null,
13      "reference_id": "219384756",
14      "reference_type": "Shipment",
15      "transaction_type": "Charge",
16      "fulfillment_center": "SB Chicago (IL)",
17      "taxes": [],
18      "additional_details": {
19        "TrackingId": "",
20        "Comment": "PO Number: WXR4821T - EachPickFee - $0.31 per each"
21      }
22    },
23    {
24      "transaction_id": "01MBX3RQNMJ7H9ZWQCF2VDKG8N",
25      "amount": 1.75,
26      "currency_code": "USD",
27      "charge_date": "2026-02-15",
28      "invoiced_status": false,
29      "invoice_date": null,
30      "transaction_fee": "B2B - Label Fee",
31      "invoice_id": null,
32      "invoice_type": null,
33      "reference_id": "219384756",
34      "reference_type": "Shipment",
35      "transaction_type": "Charge",
36      "fulfillment_center": "SB Chicago (IL)",
37      "taxes": [],
38      "additional_details": {
39        "TrackingId": "",
40        "Comment": "PO Number: WXR4821T - B2BLabelFee - $0.25 per label"
41      }
42    },
43    {
44      "transaction_id": "01MB7KPZXTCW3N6QE9YSMJRVA2",
45      "amount": 21.45,
46      "currency_code": "USD",
47      "charge_date": "2026-02-13",
48      "invoiced_status": false,
49      "invoice_date": null,
50      "transaction_fee": "Shipping",
51      "invoice_id": null,
52      "invoice_type": null,
53      "reference_id": "219384756",
54      "reference_type": "Shipment",
55      "transaction_type": "Charge",
56      "fulfillment_center": "SB Chicago (IL)",
57      "taxes": [],
58      "additional_details": {
59        "TrackingId": "784512936048",
60        "Comment": ""
61      }
62    }
63  ]
64}
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 ↗

Path Parameters

ParameterTypeRequiredDescription
invoiceIdnumberYesThe ID of the invoice

Query Parameters

ParameterTypeRequiredDescription
PagenumberNoPage number for pagination (default: 1)
PageSizenumberNoNumber of transactions per page (default: 100, max: 100)

Headers

HeaderValue
AuthorizationBearer <your_PAT>
Content-Typeapplication/json

Sample Request

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

Sample Response

1{
2  "items": [
3    {
4      "transaction_id": "01K7FHRK39R603254DSCD0YXR2",
5      "amount": 6.93,
6      "currency_code": "USD",
7      "charge_date": "2025-10-13",
8      "invoiced_status": true,
9      "invoice_date": "2025-10-14",
10      "transaction_fee": "Shipping",
11      "invoice_id": 8404298,
12      "invoice_type": "Shipping",
13      "reference_id": "305406896",
14      "reference_type": "Shipment",
15      "transaction_type": "Charge",
16      "fulfillment_center": "ShipBob Test FC (Innovation Center)",
17      "taxes": [],
18      "additional_details": {
19        "TrackingId": "9261290318421111944909",
20        "Comment": ""
21      }
22    }
23  ]
24}

Get Transaction Fees

Retrieves a list of available transaction fee types.

Endpoint
GET /2026-01/transaction-fees

API Reference ↗

Headers

HeaderValue
AuthorizationBearer <your_PAT>
Content-Typeapplication/json

Sample Request

$curl -X GET "https://api.shipbob.com/2026-01/transaction-fees" \
>-H "Authorization: Bearer <your_PAT>" \
>-H "Content-Type: application/json"

Sample Response

1{
2  "items": [
3    {
4      "fee_type": "Shipping",
5      "description": "Cost associated with shipping a package"
6    },
7    {
8      "fee_type": "WMS - Fuel Surcharge",
9      "description": "Fuel surcharge applied to shipping"
10    },
11    {
12      "fee_type": "Delivery Area Surcharge",
13      "description": "Additional fee for deliveries to specific areas"
14    },
15    {
16      "fee_type": "CreditCardProcessingFee",
17      "description": "Fee for processing credit card payments"
18    },
19    {
20      "fee_type": "AdditionalFee",
21      "description": "Miscellaneous additional fees"
22    }
23  ]
24}

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.
  • Support: For issues, contact ShipBob support via the dashboard or review the API documentation for updates.