Skip to main content
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: 
      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 ↗ 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/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 
{
  "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 ↗ 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/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 
{
  "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 ↗ 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/2025-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 /2025-07/transaction-fees API Reference ↗ Headers
HeaderValue
AuthorizationBearer <your_PAT>
Content-Typeapplication/json
Sample Request 
curl -X GET "https://api.shipbob.com/2025-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.
Last modified on December 18, 2025