Create a shipping label

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"
}'

import shippo
from shippo.models import components

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.transactions.create(request=components.TransactionCreateRequest(
    async_=False,
    label_file_type=components.LabelFileTypeEnum.PDF_4X6,
    metadata='Order ID #12345',
    rate='ec9f0d3adc9441449c85d315f0997fd5',
    order='adcfdddf8ec64b84ad22772bce3ea37a',
))

if res is not None:
    # handle response
    pass

import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: "ShippoToken <API_TOKEN>",
  shippoApiVersion: "2018-02-08",
});

async function run() {
  const result = await shippo.transactions.create({
    async: false,
    labelFileType: "PDF_4x6",
    metadata: "Order ID #12345",
    rate: "ec9f0d3adc9441449c85d315f0997fd5",
    order: "adcfdddf8ec64b84ad22772bce3ea37a",
  });

  // Handle the result
  console.log(result);
}

run();

declare(strict_types=1);

require 'vendor/autoload.php';

use Shippo\API;
use Shippo\API\Models\Components;

$sdk = API\Shippo::builder()
    ->setSecurity(
        'ShippoToken <API_TOKEN>'
    )
    ->setShippoApiVersion('2018-02-08')
    ->build();



$response = $sdk->transactions->create(
    requestBody: new Components\TransactionCreateRequest(
        async: false,
        labelFileType: Components\LabelFileTypeEnum::PDF4x6,
        metadata: 'Order ID #12345',
        rate: 'ec9f0d3adc9441449c85d315f0997fd5',
        order: 'adcfdddf8ec64b84ad22772bce3ea37a',
    ),
    shippoApiVersion: '2018-02-08'

);

if ($response->transaction !== null) {
    // handle response
}

using Shippo;
using Shippo.Models.Components;

var sdk = new ShippoSDK(
    apiKeyHeader: "ShippoToken <API_TOKEN>",
    shippoApiVersion: "2018-02-08"
);

var res = await sdk.Transactions.CreateAsync(
    requestBody: CreateTransactionRequestBody.CreateTransactionCreateRequest(
        new TransactionCreateRequest() {
            Async = false,
            LabelFileType = LabelFileTypeEnum.Pdf4x6,
            Metadata = "Order ID #12345",
            Rate = "ec9f0d3adc9441449c85d315f0997fd5",
            Order = "adcfdddf8ec64b84ad22772bce3ea37a",
        }
    ),
    shippoApiVersion: "2018-02-08"
);

// handle response

package hello.world;

import com.goshippo.shippo_sdk.Shippo;
import com.goshippo.shippo_sdk.models.components.LabelFileTypeEnum;
import com.goshippo.shippo_sdk.models.components.TransactionCreateRequest;
import com.goshippo.shippo_sdk.models.operations.CreateTransactionRequestBody;
import com.goshippo.shippo_sdk.models.operations.CreateTransactionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {

        Shippo sdk = Shippo.builder()
                .apiKeyHeader("ShippoToken <API_TOKEN>")
                .shippoApiVersion("2018-02-08")
            .build();

        CreateTransactionResponse res = sdk.transactions().create()
                .shippoApiVersion("2018-02-08")
                .requestBody(CreateTransactionRequestBody.of(TransactionCreateRequest.builder()
                    .rate("ec9f0d3adc9441449c85d315f0997fd5")
                    .async(false)
                    .labelFileType(LabelFileTypeEnum.PDF4X6)
                    .metadata("Order ID #12345")
                    .order("adcfdddf8ec64b84ad22772bce3ea37a")
                    .build()))
                .call();

        if (res.transaction().isPresent()) {
            // handle response
        }
    }
}

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    rate: 'ec9f0d3adc9441449c85d315f0997fd5',
    async: false,
    label_file_type: 'PDF_4x6',
    metadata: 'Order ID #12345',
    order: 'adcfdddf8ec64b84ad22772bce3ea37a'
  })
};

fetch('https://api.goshippo.com/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.goshippo.com/transactions"

	payload := strings.NewReader("{\n  \"rate\": \"ec9f0d3adc9441449c85d315f0997fd5\",\n  \"async\": false,\n  \"label_file_type\": \"PDF_4x6\",\n  \"metadata\": \"Order ID #12345\",\n  \"order\": \"adcfdddf8ec64b84ad22772bce3ea37a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.goshippo.com/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"rate\": \"ec9f0d3adc9441449c85d315f0997fd5\",\n  \"async\": false,\n  \"label_file_type\": \"PDF_4x6\",\n  \"metadata\": \"Order ID #12345\",\n  \"order\": \"adcfdddf8ec64b84ad22772bce3ea37a\"\n}"

response = http.request(request)
puts response.read_body

{
  "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_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"
}

{}

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"
}'

import shippo
from shippo.models import components

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.transactions.create(request=components.TransactionCreateRequest(
    async_=False,
    label_file_type=components.LabelFileTypeEnum.PDF_4X6,
    metadata='Order ID #12345',
    rate='ec9f0d3adc9441449c85d315f0997fd5',
    order='adcfdddf8ec64b84ad22772bce3ea37a',
))

if res is not None:
    # handle response
    pass

import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: "ShippoToken <API_TOKEN>",
  shippoApiVersion: "2018-02-08",
});

async function run() {
  const result = await shippo.transactions.create({
    async: false,
    labelFileType: "PDF_4x6",
    metadata: "Order ID #12345",
    rate: "ec9f0d3adc9441449c85d315f0997fd5",
    order: "adcfdddf8ec64b84ad22772bce3ea37a",
  });

  // Handle the result
  console.log(result);
}

run();

declare(strict_types=1);

require 'vendor/autoload.php';

use Shippo\API;
use Shippo\API\Models\Components;

$sdk = API\Shippo::builder()
    ->setSecurity(
        'ShippoToken <API_TOKEN>'
    )
    ->setShippoApiVersion('2018-02-08')
    ->build();



$response = $sdk->transactions->create(
    requestBody: new Components\TransactionCreateRequest(
        async: false,
        labelFileType: Components\LabelFileTypeEnum::PDF4x6,
        metadata: 'Order ID #12345',
        rate: 'ec9f0d3adc9441449c85d315f0997fd5',
        order: 'adcfdddf8ec64b84ad22772bce3ea37a',
    ),
    shippoApiVersion: '2018-02-08'

);

if ($response->transaction !== null) {
    // handle response
}

using Shippo;
using Shippo.Models.Components;

var sdk = new ShippoSDK(
    apiKeyHeader: "ShippoToken <API_TOKEN>",
    shippoApiVersion: "2018-02-08"
);

var res = await sdk.Transactions.CreateAsync(
    requestBody: CreateTransactionRequestBody.CreateTransactionCreateRequest(
        new TransactionCreateRequest() {
            Async = false,
            LabelFileType = LabelFileTypeEnum.Pdf4x6,
            Metadata = "Order ID #12345",
            Rate = "ec9f0d3adc9441449c85d315f0997fd5",
            Order = "adcfdddf8ec64b84ad22772bce3ea37a",
        }
    ),
    shippoApiVersion: "2018-02-08"
);

// handle response

package hello.world;

import com.goshippo.shippo_sdk.Shippo;
import com.goshippo.shippo_sdk.models.components.LabelFileTypeEnum;
import com.goshippo.shippo_sdk.models.components.TransactionCreateRequest;
import com.goshippo.shippo_sdk.models.operations.CreateTransactionRequestBody;
import com.goshippo.shippo_sdk.models.operations.CreateTransactionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {

        Shippo sdk = Shippo.builder()
                .apiKeyHeader("ShippoToken <API_TOKEN>")
                .shippoApiVersion("2018-02-08")
            .build();

        CreateTransactionResponse res = sdk.transactions().create()
                .shippoApiVersion("2018-02-08")
                .requestBody(CreateTransactionRequestBody.of(TransactionCreateRequest.builder()
                    .rate("ec9f0d3adc9441449c85d315f0997fd5")
                    .async(false)
                    .labelFileType(LabelFileTypeEnum.PDF4X6)
                    .metadata("Order ID #12345")
                    .order("adcfdddf8ec64b84ad22772bce3ea37a")
                    .build()))
                .call();

        if (res.transaction().isPresent()) {
            // handle response
        }
    }
}

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    rate: 'ec9f0d3adc9441449c85d315f0997fd5',
    async: false,
    label_file_type: 'PDF_4x6',
    metadata: 'Order ID #12345',
    order: 'adcfdddf8ec64b84ad22772bce3ea37a'
  })
};

fetch('https://api.goshippo.com/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.goshippo.com/transactions"

	payload := strings.NewReader("{\n  \"rate\": \"ec9f0d3adc9441449c85d315f0997fd5\",\n  \"async\": false,\n  \"label_file_type\": \"PDF_4x6\",\n  \"metadata\": \"Order ID #12345\",\n  \"order\": \"adcfdddf8ec64b84ad22772bce3ea37a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.goshippo.com/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"rate\": \"ec9f0d3adc9441449c85d315f0997fd5\",\n  \"async\": false,\n  \"label_file_type\": \"PDF_4x6\",\n  \"metadata\": \"Order ID #12345\",\n  \"order\": \"adcfdddf8ec64b84ad22772bce3ea37a\"\n}"

response = http.request(request)
puts response.read_body

{
  "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_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

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.

Create request to purchase label with a Rate
Create request to purchase label without a Rate (Instalabel)

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

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.

Show child attributes

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[]

Show child attributes

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.

Show child attributes

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"

Last modified on July 16, 2026

Overview

Shippo API

Enums

Addresses API v2

Authorizations

Headers

Body

Response