API Changelog
We will be documenting all backwards-incompatible changes associated with each new API version here on the changelog. Learn more about how Shippo API versioning works and upgrade to the latest.
Version 2018-02-08
Carrier Accounts
For security reasons, the account_id
and parameters
fields will be censored in the response objects.
Tracks
PRE_TRANSIT will be added to the list of possible values in status
.
Webhooks
PRE_TRANSIT will be added to the list of possible values in status
and tracking_status
for track_updated
and transaction_updated
events, respectively.
Version 2017-08-01
Webhooks
Shippo-API-Version
will be included in the headers of all webhook responses to indicate the api version being used.
New events have been added to our webhooks:
transaction_updated
– will be triggered when a transaction in your account is updated, and will provide the updated transaction.transaction_created
– will be triggered when a transaction in your account is created, and will provide the updated transaction.
A new fields have been added in the body of the webhook payload:
event_type
will have one of the following values:transaction_created
,transaction_updated
,track_updated
,batch_created
, orbatch_updated
.
Please see our Webhooks tutorials for examples of using these new fields and events.
All Endpoints
The count
field has been removed. If making a GET request to any endpoint without an object_id
specified in the URI (i.e. /transactions, /shipments, /addresses) you will no longer see the count
field in the body of the response.
Rates
In rate objects, the days
field has been renamed to estimated_days
to make it clear that this is an estimate.
Transactions
Version 2017-03-29
Major Update: Refactored and Deprecated Fields
In this API version, we’ve cleaned up many stale attributes across various endpoints in the API to make them more intuitive and true to operational use cases. Please explore the following to see if any changes will affect your implementation.
The changes to our Shipments endpoint for returns now makes it possible to create return labels without having to reference a previous transaction.
Changes have been made to the following endpoints: Addresses, Shipments, Rates, Transactions, Batches, and Refunds. For more detailed information, please see the full API references.
Addresses
Request:
-
Deprecated:
object_purpose
Response:
-
Deprecated:
ip
object_purpose
object_state
object_source
-
Added:
is_complete
— boolean used to indicate if an address is fully entered, making it possible to use for purchasing a label.validation_results
— object that contains information regarding if an address had been validated or not. Also contains any messages generated during validation. Children keys areis_valid
(boolean) andmessages
(array).
-
Updated:
messages
has been moved into newvalidation_results
field.
Shipments
Request:
-
Deprecated:
object_purpose
-
Updated:
submission_date
is nowshipment_date
return_of
is nowis_return
, also has been changed to a boolean and is no longer a top-level key and has been moved into extra field. This will flag a shipment to be created as a scan-based label.object_status
is nowstatus
insurance_amount
is nowamount
, moved into newly addedinsurance
field insideextra
object.insurance_currency
is nowcurrency
, moved into newly addedinsurance
field insideextra
object.insurance_provider
is nowprovider
, moved into newly addedinsurance
field.insurance_content
is nowcontent
, moved into newly addedinsurance
field.reference_1
&reference_2
moved toextra
field.parcel
is nowparcels
and has been changed to an array.
- Added:
insurance
, an object within theextra
object with previous top level andextra
level insurance fields as keys of theinsurance
object.
Response:
-
Deprecated:
object_state
submission_type
object_purpose
rates_url
-
Updated:
rates_list
is nowrates
submission_date
is nowshipment_date
return_of
is nowis_return
, also has been changed to a boolean and is no longer a top-level key and has been moved into theextra
field. This will set the shipment as a return shipment, which makes the label scan-based. See our docs on Returns for more information.object_status
is nowstatus
insurance_amount
is nowamount
, moved into newly addedinsurance
field.insurance_currency
is nowcurrency
, moved into newly addedinsurance
field.insurance_content
is nowcontent
, moved into newly addedinsurance
field.insurance_provider
is nowprovider
, moved into newly addedinsurance
field.reference_1
&reference_2
moved toextra
field.address_to
,address_from
,address_return
, andparcel
are now expanded to include full address or parcel information, in addition to theirobject_id
.parcel
is nowparcels
and has been changed to an array.
-
Added:
insurance
, an object within theextra
object with previous insurance fields as keys of theinsurance
object.
Rates
Request:
-
Deprecated:
- GET on /rates/ will no longer return a list of rates. GET on /rates/{object_id} will still work as indicated.
Response:
-
Deprecated:
object_state
object_purpose
object_updated
trackable
delivery_attempts
rates_url
-
Updated:
servicelevel_name
,servicelevel_token
, andservicelevel_terms
have been renamed toname
,token
, andterms
(respectively) and moved into the newly createdservicelevel
field.
-
Added:
servicelevel
, object that contains renamed fields:name
,token
, andterms
(previouslyservicelevel_name
,servicelevel_token
, andservicelevel_terms
)
Transactions
Response:
-
Deprecated:
customs_note
submission_note
-
Updated:
object_state
is nowstatus
rate
field is expanded with full rate details for insta-label calls.
Manifest
Request:
-
Updated:
submission_date
is nowshipment_date
Response:
-
Updated:
submission_date
is nowshipment_date
Batches
Response:
-
Updated:
object_status
is nowstatus
Refunds
Response:
-
Updated:
object_status
is nowstatus
Parcel
Request:
-
Updated:
reference_1
andreference_2
can be added in theextra
field of Parcel for multi-parcel shipments. See Multi-Piece Shipments for more information.
Version 2016-10-25
Major Update: New Test Token used to set Shippo to test mode.
You will now be able use all Shippo API functionalities from end-to-end in test mode by authenticating requests with a Test Token. Previously, to test out Shippo, you had to set carrier accounts to test mode. Now all users will have have two different tokens: one for test mode and one for live mode.
For users continuing to use API version 2014-02-11
You will have the option of using the Test Token while remaining on the older version of the Shippo API.
- Test Token can be used for test mode without affecting your existing implementation. See our Test Mode documentation to learn more about functionalities.
- Functionalities of your existing Private Auth Token will remain the same – now renamed as “Live Token”.
- All tokens will now begin with
"shippo_live_"
or"shippo_test_"
. This will not affect any existing implementation with old tokens, however we recommend using the new format going forward.
For users upgrading to API version 2016-10-25
Using the Test Token and Live Token will affect how your test and live data are returned and displayed.
Test and Live Data
- When using the Test Token, you will only be able to create and request test data sets such as addresses, rates, and carriers etc. No live data can be requested or returned.
- When using the Live Token, you will only be able to create and request live data. No test data can be requested or returned.
- Shipment object will now return 3 variables for
test
- True – All Rates returned in Shipment were tests
- False – All Rates returned in Shipment were live
- None – Rates returned in Shipment were both tests and live
The following are some common scenarios.
- If you create a Shipment with Live Token using an Address object created with a Test Token, you will receive a 404 response (not found). Vice versa is also true. If you retrieve an object_id created in live mode with a Test Token, you will receive a 403 (bad request) response.
- If you request a list of Transaction objects, or Shipment objects with the Test Token, only test Transactions or Shipments will be returned. Vice versa is also true, when making requests in live mode.
Carrier account configuration
When you upgrade to the latest version, the test
attribute of the carrier object will become read-only.
- User-owned carrier accounts (where you have plugged in your own carrier credentials) that have been set to
test: true
at the time of upgrade will only appear and work when request with a Test Token. - User-owned carrier accounts (where you have plugged in your own carrier credentials) that have been set to
test: false
at the time of upgrade will only appear and work when request with a Live Token. - Shippo-owned master accounts (see carrier capabilities for full list) object_ids will appear and be functional when requested with a Test Token or a Live Token.
We recommend setting all carrier accounts to test: false
(including on your dashboard) before upgrading so that existing carrier accounts are set to live mode. This will help with minimizing changes necessary for the upgrade.
“test” attribute
Certain objects will now be returning a new “test”
attribute.
- Transaction object will no longer return the “was_test” attribute, instead it will return “test”.
- Address, Parcel, Refund, Customs Declaration, and Customs Items objects will now return a new “test” attribute.
- Possible values for “test”:
- True – the object was created in test mode
- False – the object was created in live mode
- Other objects (such as Carrier Accounts and Rates) will keep returning “test” if they did in past.