Billing | ShipBob Developer API

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:

Verify billing_read Scope:
- Make a request to the GET /2026-07/channel endpoint to confirm your PAT includes the billing_read scope.
- Sample Request:
```
curl -X GET "https://api.shipbob.com/2026-07/channel" \
-H "Authorization: Bearer <your_PAT>" \
-H "Content-Type: application/json"
```
- If the response indicates the billing_read scope is missing, generate a new PAT.
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-07/invoices

API Reference ↗

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

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

{
  "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-07/transactions:query

API Reference ↗

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

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

{
  "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-07/transactions:query and filter by the shipment’s reference_id.

Endpoint
POST /2026-07/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

Header	Value
`Authorization`	`Bearer <your_PAT>`
`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

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

Sample Response

{
  "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-07/invoices/{invoiceId}/transactions

API Reference ↗

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

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

Sample Response

{
  "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-07/transaction-fees

API Reference ↗

Headers

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

Sample Request

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

Sample Response

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