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 /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.

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

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/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

expandable

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 /2025-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/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

expandable

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 Transactions by Invoice ID

Retrieves all transactions associated with a specific invoice ID.

Endpoint
GET /2025-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/2025-07/invoices/8404298/transactions?Page=1&PageSize=50" \
> -H "Authorization: Bearer <your_PAT>" \
> -H "Content-Type: application/json"

Sample Response

expandable

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 /2025-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/2025-07/transaction-fees" \
> -H "Authorization: Bearer <your_PAT>" \
> -H "Content-Type: application/json"

Sample Response

expandable

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.