Skip to navigation
API ReferenceBilling

Get Cost by Reference

View as Markdown

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.

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

OR
AuthorizationBearer
OAuth2 authentication using JWT tokens

Path parameters

reference_typeenumRequired
The type of the reference to return the cost for. Currently only Shipment is supported.
Allowed values:
reference_idstringRequired
The identifier of the reference to return the cost for. For a Shipment, this is the ShipBob shipment ID.

Query parameters

expandlist of enumsOptional

[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:
transaction_feesstringOptional

[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

Success
billed_to_user_idintegerOptional
The identifier of the user the reference is billed to.
cost_revisionlongOptional
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_idstringOptional
The identifier of the reference the cost is for.
reference_typestringOptional
The type of the reference the cost is for.
reference_type_idintegerOptional
The identifier of the reference type.
totalslist of objectsOptional

The cost totals for the whole reference, one entry per currency. Totals are not affected by the ‘transaction_fees’ filter.

transactionslist of objectsOptional

The transactions behind the totals. Only returned when ‘transactions’ or ‘calculation_basis’ is passed in ‘expand’.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error