> This page is for version 2026-07 (default). > For other versions, use one of these documentation indexes: > - 2026-07 (default): https://developer-dev.shipbob.dev/2026-07/llms.txt > - 2026-01: https://developer-dev.shipbob.dev/2026-01/llms.txt > - 2025-07: https://developer-dev.shipbob.dev/2025-07/llms.txt > - v2.0: https://developer-dev.shipbob.dev/v2.0/llms.txt > - v1.0: https://developer-dev.shipbob.dev/v1.0/llms.txt > - Experimental: https://developer-dev.shipbob.dev/experimental/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer-dev.shipbob.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-dev.shipbob.dev/_mcp/server. # Get Cost by Reference GET https://gateway-dev.shipbob.dev/2026-07/costs/{reference_type}/{reference_id} Returns the cost of a single reference, such as a shipment. The response always includes the net total for the whole reference, with one entry per currency. Pass `expand=transactions` to also return the transactions behind the total, and `expand=calculation_basis` to also return the inputs behind each Shipping transaction. Use `transaction_fees` to narrow the returned transactions to one fee type; the totals always describe the whole reference. Returns 404 if the reference has no transactions or does not belong to you. Reference: https://developer-dev.shipbob.dev/api/billing/get-cost-by-reference ## Authentication - `Authorization` header (bearer token, required) — Authentication using Personal Access Token (PAT) token - `Authorization` header (bearer token, required) — OAuth2 authentication using JWT tokens ## Request ### Path parameters - `reference_type` (enum, required) — The type of the reference to return the cost for. Currently only Shipment is supported. - Allowed values: `Shipment` - `reference_id` (string, required) — The identifier of the reference to return the cost for. For a Shipment, this is the ShipBob shipment ID. ### Query parameters - `expand` (list of enum, optional) — [Optional] Additional detail to include in the response. Repeat the parameter to pass more than one value. 'transactions' returns the transactions behind the total. 'calculation_basis' returns the inputs behind each Shipping transaction, and also returns the transactions. - Allowed values: `transactions`, `calculation_basis` - `transaction_fees` (string, optional) — [Optional] A single transaction fee type to narrow the returned transactions to, for example Shipping. It does not change the totals. Only applies when transactions are returned. ## Response ### 200 Success - `billed_to_user_id` (integer, optional) — The identifier of the user the reference is billed to. - `cost_revision` (long, optional) — The revision of the reference's cost. It increases whenever a new transaction is recorded for the reference, so you can use it to tell whether a copy of this cost you have stored is current. - `reference_id` (string, optional) — The identifier of the reference the cost is for. - `reference_type` (string, optional) — The type of the reference the cost is for. - `reference_type_id` (integer, optional) — The identifier of the reference type. - `totals` (list of Billing.CostTotalByCurrency, optional) — The cost totals for the whole reference, one entry per currency. Totals are not affected by the 'transaction_fees' filter. - `transactions` (list of Billing.CostTransactionLine, optional) — The transactions behind the totals. Only returned when 'transactions' or 'calculation_basis' is passed in 'expand'. ## Errors ### 400 Bad Request Error Bad Request - `detail` (string, optional, nullable) - `instance` (string, optional, nullable) - `status` (integer, optional, nullable) - `title` (string, optional, nullable) - `type` (string, optional, nullable) ### 401 Unauthorized Error Authorization missing or invalid - `any` ### 403 Forbidden Error The provided credentials are not authorized to access this resource - `any` ### 404 Not Found Error Not Found - `detail` (string, optional, nullable) - `instance` (string, optional, nullable) - `status` (integer, optional, nullable) - `title` (string, optional, nullable) - `type` (string, optional, nullable) ### 500 Internal Server Error Server Error - `any` ## Types ### Billing.CostTotalByCurrency The cost totals for a reference in a single currency. - `currency_code` (string, optional) — The ISO currency code (e.g., USD, EUR) these totals are in. Totals are never converted or blended across currencies. - `net_total` (double, optional) — The net cost for the reference in this currency: total charges minus total refunds minus total credits. - `total_charges` (double, optional) — The sum of all charges for the reference in this currency. - `total_credits` (double, optional) — The sum of all credits for the reference in this currency. - `total_refunds` (double, optional) — The sum of all refunds for the reference in this currency. ### Billing.CostTransactionLine A single transaction that contributes to the cost of a reference. - `additional_details` (map from string to any, optional, nullable) — Additional details about the transaction in a key-value pair format. The keys depend on the invoice type: Shipping, Return and AdditionalFee transactions return 'tracking_id' and 'comment'; WarehouseStorage transactions return 'inventory_id', 'location_type', 'tracking_id' and 'comment'; Credits transactions return 'credit_reason' and 'ticket_reference'. A key with no value is returned as an empty string. Omitted for any other invoice type. - `amount` (double, optional) — The amount of the transaction, as invoiced. Charges are positive; refunds and credits are negative, so, without a 'transaction_fees' filter, the amounts of all transactions add up to the net total. - `calculation_basis` (Billing.CostCalculationBasis, optional, nullable) — The inputs behind the transaction amount. Only returned when 'calculation_basis' is passed in 'expand'. Null for transactions that are not Shipping, or when the calculation inputs are unavailable. - `currency_code` (string, optional) — The ISO currency code (e.g., USD, EUR) for the transaction. - `insert_date` (datetime, optional) — The date and time the transaction was recorded. - `invoice_date` (datetime, optional, nullable) — The date the invoice was generated. Null until the transaction is invoiced. - `invoice_id` (integer, optional, nullable) — The unique identifier of the invoice associated with this transaction. Null until the transaction is invoiced. - `invoice_type` (string, optional, nullable) — The type or category of the invoice. Null until the transaction is invoiced. - `invoiced` (boolean, optional) — Indicates whether the transaction has been invoiced. True if billed, false if unbilled. - `taxes` (list of Billing.CostTaxLine, optional) — A list of tax details applied to the transaction. Empty if no tax applies. - `transaction_fee` (string, optional) — The fee type associated with the transaction. To get all available transaction fees, use the '/transaction-fees' endpoint. - `transaction_fee_id` (integer, optional) — The identifier of the fee type associated with the transaction. - `transaction_id` (string, optional) — The unique identifier for the transaction. - `transaction_type` (enum, optional) — The classification of the transaction. - Allowed values: `Charge`, `Refund`, `Credit` - `transaction_type_id` (integer, optional) — The identifier of the transaction type. ### Billing.CostCalculationBasis The inputs behind the amount of a Shipping transaction. A Shipping charge returns the zone, billable weight and dimensional divisor; a value that is unavailable is returned as null. A Shipping refund or credit returns only the reason, as an empty string if none is recorded. - `billable_weight` (double, optional, nullable) — The billable weight the shipment was priced on. Returned for Shipping charges. - `dim_divisor` (integer, optional, nullable) — The dimensional weight divisor used to calculate the billable weight. Returned for Shipping charges. - `reason` (string, optional, nullable) — The reason given for the refund or credit. Returned for Shipping refunds and credits. - `shipbob_zone_id` (integer, optional, nullable) — The ShipBob zone the shipment was priced in. Returned for Shipping charges. ### Billing.CostTaxLine Tax information associated with a cost transaction. - `tax_amount` (double, optional) — Tax amount charged for this tax type. - `tax_rate` (double, optional) — Tax rate applied as a percentage. - `tax_type_id` (integer, optional) — The identifier of the type of tax applied. 1 = GST, 2 = Sales Tax. ## Examples **Response** ```json { "billed_to_user_id": 1000, "cost_revision": 908070605, "reference_id": "100000001", "reference_type": "Shipment", "reference_type_id": 1, "totals": [ { "currency_code": "USD", "net_total": 6.93, "total_charges": 8.13, "total_credits": 0, "total_refunds": 1.2 } ], "transactions": [ { "additional_details": { "comment": "", "tracking_id": "TRACK123456789" }, "amount": 8.13, "calculation_basis": { "billable_weight": 20, "dim_divisor": 166, "shipbob_zone_id": 12 }, "currency_code": "USD", "insert_date": "2026-07-01T18:04:22+00:00", "invoice_date": "2026-07-02T06:00:00+00:00", "invoice_id": 12345, "invoice_type": "Shipping", "invoiced": true, "taxes": [], "transaction_fee": "Shipping", "transaction_fee_id": 1, "transaction_id": "01AN4Z07BY79KA1307SR9X4MV3", "transaction_type": "Charge", "transaction_type_id": 1 }, { "additional_details": { "comment": "", "tracking_id": "TRACK123456789" }, "amount": -1.2, "calculation_basis": { "reason": "Incorrect weight" }, "currency_code": "USD", "insert_date": "2026-07-03T09:15:40+00:00", "invoice_date": "2026-07-04T06:00:00+00:00", "invoice_id": 12346, "invoice_type": "Shipping", "invoiced": true, "taxes": [], "transaction_fee": "Shipping", "transaction_fee_id": 1, "transaction_id": "01AN4Z07BY79KA1307SR9X4MV4", "transaction_type": "Refund", "transaction_type_id": 2 } ] } ``` **SDK Code** ```python default import requests url = "https://gateway-dev.shipbob.dev/2026-07/costs/Shipment/100000001" querystring = {"expand":"[\"transactions\",\"calculation_basis\"]","transaction_fees":"Shipping"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript default const url = 'https://gateway-dev.shipbob.dev/2026-07/costs/Shipment/100000001?expand=%5B%22transactions%22%2C%22calculation_basis%22%5D&transaction_fees=Shipping'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go default package main import ( "fmt" "net/http" "io" ) func main() { url := "https://gateway-dev.shipbob.dev/2026-07/costs/Shipment/100000001?expand=%5B%22transactions%22%2C%22calculation_basis%22%5D&transaction_fees=Shipping" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby default require 'uri' require 'net/http' url = URI("https://gateway-dev.shipbob.dev/2026-07/costs/Shipment/100000001?expand=%5B%22transactions%22%2C%22calculation_basis%22%5D&transaction_fees=Shipping") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java default import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://gateway-dev.shipbob.dev/2026-07/costs/Shipment/100000001?expand=%5B%22transactions%22%2C%22calculation_basis%22%5D&transaction_fees=Shipping") .header("Authorization", "Bearer ") .asString(); ``` ```php default request('GET', 'https://gateway-dev.shipbob.dev/2026-07/costs/Shipment/100000001?expand=%5B%22transactions%22%2C%22calculation_basis%22%5D&transaction_fees=Shipping', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp default using RestSharp; var client = new RestClient("https://gateway-dev.shipbob.dev/2026-07/costs/Shipment/100000001?expand=%5B%22transactions%22%2C%22calculation_basis%22%5D&transaction_fees=Shipping"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift default import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://gateway-dev.shipbob.dev/2026-07/costs/Shipment/100000001?expand=%5B%22transactions%22%2C%22calculation_basis%22%5D&transaction_fees=Shipping")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```