Skip to main content
POST
/
transactions
cURL
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken {{token}}' \
--header 'Content-Type: application/json' \
--header 'SHIPPO-API-VERSION: 2018-02-08' \
--data-raw '{
  "rate": "a5c9d1bec93149f5bedc3a9374b50970",
  "async": false,
  "label_file_type": "PDF"
}'
{
  "commercial_invoice_url": "<string>",
  "created_by": {
    "first_name": "Shwan",
    "last_name": "Ippotle",
    "username": "shippotle@shippo.com"
  },
  "eta": "<string>",
  "label_file_type": "PDF_4x6",
  "label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
  "messages": [
    {
      "source": "UPS",
      "code": "carrier_timeout",
      "text": "UPS API did not respond. Please try again in a few minutes."
    }
  ],
  "metadata": "<string>",
  "object_created": "2023-11-07T05:31:56Z",
  "object_id": "915d94940ea54c3a80cbfa328722f5a1",
  "object_owner": "shippotle@shippo.com",
  "object_state": "VALID",
  "object_updated": "2023-11-07T05:31:56Z",
  "parcel": "e94c7fdfdc7b495dbb390a28d929d90a",
  "qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
  "rate": {
    "amount": "5.5",
    "amount_local": "5.5",
    "currency": "USD",
    "currency_local": "USD",
    "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
    "provider": "USPS",
    "carrier_account": "078870331023437cb917f5187429b093",
    "servicelevel_name": "Priority Mail",
    "servicelevel_token": "fedex_ground"
  },
  "status": "SUCCESS",
  "test": true,
  "tracking_number": "9499907123456123456781",
  "tracking_status": "DELIVERED",
  "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
}

Authorizations

​
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

Examples.

​
rate
string
required
Example:

"ec9f0d3adc9441449c85d315f0997fd5"

​
async
boolean
default:true
Example:

false

​
label_file_type
enum<string>

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

Available options:
PNG,
PNG_2.3x7.5,
PDF,
PDF_2.3x7.5,
PDF_4x6,
PDF_4x8,
PDF_A4,
PDF_A5,
PDF_A6,
ZPLII
Example:

"PDF_4x6"

​
metadata
string
Example:

"Order ID #12345"

​
order
string
Example:

"adcfdddf8ec64b84ad22772bce3ea37a"

Response

Created transaction

​
commercial_invoice_url
string

A URL pointing to the commercial invoice as a 8.5x11 inch PDF file. A value will only be returned if the Transactions has been processed successfully and if the shipment is international.

​
created_by
object

An object with details about the user who created the Transaction (purchased the label). A value will be returned only for Transactions that can be associated with a specific user, e.g. when a logged-in user purchases a label via the Shippo Web application; but not for Transactions purchased e.g. via the API using a ShippoToken, which is associated with the account but not any specific user.

​
eta
string

The estimated time of arrival according to the carrier.

​
label_file_type
enum<string>

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

Available options:
PNG,
PNG_2.3x7.5,
PDF,
PDF_2.3x7.5,
PDF_4x6,
PDF_4x8,
PDF_A4,
PDF_A5,
PDF_A6,
ZPLII
Example:

"PDF_4x6"

​
label_url
string

A URL pointing directly to the label in the format you've set in your settings. A value will only be returned if the Transactions has been processed successfully.

Example:

"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"

​
messages
object[]
​
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

​
object_created
string<date-time>

Date and time of Transaction creation.

​
object_id
string

Unique identifier of the given Transaction object.

Example:

"915d94940ea54c3a80cbfa328722f5a1"

​
object_owner
string

Username of the user who created the Transaction object.

Example:

"shippotle@shippo.com"

​
object_state
enum<string>

Indicates the validity of the enclosing object

Available options:
VALID,
INVALID
​
object_updated
string<date-time>

Date and time of last Transaction update.

​
parcel
string

Object ID of the Parcel object that is being shipped.

Example:

"e94c7fdfdc7b495dbb390a28d929d90a"

​
qr_code_url
string

A URL pointing directly to the QR code in PNG format. A value will only be returned if requested using qr_code_requested flag and the carrier provides such an option.

Example:

"https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"

​
rate

ID of the Rate object for which a Label has to be obtained.
If you purchase a label by calling the transaction endpoint without a rate (instalabel), this field will be a simplified Rate object in the Transaction model returned from the POST request.
Note, only rates less than 7 days old can be purchased to ensure up-to-date pricing.

​
status
enum<string>

Indicates the status of the Transaction.

Available options:
WAITING,
QUEUED,
SUCCESS,
ERROR,
REFUNDED,
REFUNDPENDING,
REFUNDREJECTED
Example:

"SUCCESS"

​
test
boolean

Indicates whether the object has been created in test mode.

​
tracking_number
string

The carrier-specific tracking number that can be used to track the Shipment. A value will only be returned if the Rate is for a trackable Shipment and if the Transactions has been processed successfully.

Example:

"9499907123456123456781"

​
tracking_status
enum<string>

Indicates the high level status of the shipment.

Available options:
UNKNOWN,
PRE_TRANSIT,
TRANSIT,
DELIVERED,
RETURNED,
FAILURE
Example:

"DELIVERED"

​
tracking_url_provider
string

A link to track this item on the carrier-provided tracking website. A value will only be returned if tracking is available and the carrier provides such a service.

Example:

"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"