Ship Toolkit API

The hosted label and PDF endpoints accept JSON over HTTPS and return generated PDF files directly. Keep API keys out of source code and send them as bearer tokens.

Quick Start

Base URLhttps://shiptoolkit.com

MethodPOST for hosted generation APIs

AuthAuthorization: Bearer <api-key>

BodyContent-Type: application/json

IdempotencyIdempotency-Key: <unique value>

Successapplication/pdf

Hosted label and PDF APIs require an API key. To request access, contact shiptoolkit@element-express.com.

Successful PDF responses include Content-Disposition, X-Page-Count, X-Content-SHA256, and either X-Label-Type or X-PDF-Operation. Error responses are JSON with an error field.

{
  "standardLabelSize": [
    "2.00x1.00",
    "2.25x1.25",
    "2.50x1.00",
    "3.00x1.00",
    "3.00x1.50",
    "3.00x2.00",
    "4.00x2.00",
    "50x30mm",
    "60x30mm",
    "60x40mm"
  ],
  "cartonMarkLabelSize": ["6x4", "4x4", "4x3", "4x2"]
}

Python helper

import base64
import json
import os
import uuid
import urllib.request
from pathlib import Path

BASE_URL = "https://shiptoolkit.com"
API_KEY = os.environ["SHIPTOOLKIT_API_KEY"]

def post_pdf(path, payload, output_file):
    request = urllib.request.Request(
        BASE_URL + path,
        data=json.dumps(payload).encode("utf-8"),
        method="POST",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
            "Idempotency-Key": str(uuid.uuid4()),
            "User-Agent": "ShipToolkit-API-Example/1.0",
        },
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        pdf = response.read()
        if not pdf.startswith(b"%PDF-"):
            raise RuntimeError("Ship Toolkit returned a non-PDF response.")
    Path(output_file).write_bytes(pdf)

def pdf_base64(filename):
    return base64.b64encode(Path(filename).read_bytes()).decode("ascii")

Java helper

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;
import java.util.UUID;

class ShipToolkitApi {
    static final String BASE_URL = "https://shiptoolkit.com";
    static final String API_KEY = System.getenv("SHIPTOOLKIT_API_KEY");
    static final HttpClient CLIENT = HttpClient.newHttpClient();

    static void postPdf(String path, String json, Path outputFile)
            throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + path))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", UUID.randomUUID().toString())
            .header("User-Agent", "ShipToolkit-API-Example/1.0")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        HttpResponse<byte[]> response = CLIENT.send(
            request,
            HttpResponse.BodyHandlers.ofByteArray()
        );
        if (response.statusCode() != 200) {
            throw new IOException("Ship Toolkit API failed: " + response.statusCode());
        }
        Files.write(outputFile, response.body());
    }

    static String pdfBase64(Path file) throws IOException {
        return Base64.getEncoder().encodeToString(Files.readAllBytes(file));
    }
}

Label APIs

These endpoints return PDF label files and require a bearer API key.

POST /v1/labels/amazon-fnsku

Create an Amazon product label from a 10-character FNSKU.

Field	Type	Required	Default	Constraints
`sku`	`string`	`true`	`-`	`pattern: ^[A-Z0-9]{10}$`
`model`	`string`	`true`	`-`	`maxLength: 240`
`title`	`string`	`true`	`-`	`maxLength: 500`
`madeIn`	`string`	`true`	`-`	`maxLength: 80`
`labelSize`	`enum`	`true`	`-`	`standardLabelSize`
`oldSku`	`string`	`false`	`""`	`maxLength: 128`
`productCondition`	`enum`	`false`	`"other"`	`["new", "other"]`

Python

payload = {
    "sku": "X001ABC123",
    "model": "ABC-123",
    "title": "Sample product",
    "madeIn": "China",
    "productCondition": "new",
    "labelSize": "2.25x1.25",
    "oldSku": "OLD-123",
}
post_pdf("/v1/labels/amazon-fnsku", payload, "amazon-fnsku.pdf")

Java

String json = """
{
  "sku": "X001ABC123",
  "model": "ABC-123",
  "title": "Sample product",
  "madeIn": "China",
  "productCondition": "new",
  "labelSize": "2.25x1.25",
  "oldSku": "OLD-123"
}
""";
ShipToolkitApi.postPdf(
    "/v1/labels/amazon-fnsku",
    json,
    Path.of("amazon-fnsku.pdf")
);

POST /v1/labels/amazon-fba-ups

Add text overlays to Amazon FBA and UPS labels, then return 4 x 6 inch output pages with optional scaling and duplicate copies.

Field	Type	Required	Default	Constraints
`pdfBase64`	`string`	`true`	`-`	`maxBytes: 7MB`
`filename`	`string`	`false`	`"amazon-fba-ups-labels.pdf"`	`maxLength: 160`
`fbaText`	`string`	`false`	`""`	`maxLength: 500`
`upsText`	`string`	`false`	`""`	`maxLength: 500`
`scalePercent`	`number`	`false`	`95`	`min: 1, max: 100`
`twoFbaCopies`	`boolean`	`false`	`false`	`-`
`twoUpsCopies`	`boolean`	`false`	`false`	`requires twoFbaCopies`

Python

payload = {
    "pdfBase64": pdf_base64("fba-ups-source.pdf"),
    "filename": "fba-ups-source.pdf",
    "fbaText": "BOX 1",
    "upsText": "CARTON A",
    "scalePercent": 95,
    "twoFbaCopies": False,
    "twoUpsCopies": False,
}
post_pdf("/v1/labels/amazon-fba-ups", payload, "fba-ups-labels.pdf")

Java

String source = ShipToolkitApi.pdfBase64(Path.of("fba-ups-source.pdf"));
String json = """
{
  "pdfBase64": "%s",
  "filename": "fba-ups-source.pdf",
  "fbaText": "BOX 1",
  "upsText": "CARTON A",
  "scalePercent": 95
}
""".formatted(source);
ShipToolkitApi.postPdf(
    "/v1/labels/amazon-fba-ups",
    json,
    Path.of("fba-ups-labels.pdf")
);

Source pages may be native 4 x 6, 4.25 x 6, or US Letter pages with two labels. US Letter pages use the built-in two-label crop layout.

POST /v1/labels/walmart-sku

Create a Walmart fulfillment product label from a 14-digit Walmart SKU.

Field	Type	Required	Default	Constraints
`sku`	`string`	`true`	`-`	`pattern: ^\d{14}$`
`model`	`string`	`true`	`-`	`maxLength: 240`
`title`	`string`	`true`	`-`	`maxLength: 500`
`madeIn`	`string`	`true`	`-`	`maxLength: 80`
`labelSize`	`enum`	`true`	`-`	`standardLabelSize`
`productCondition`	`enum`	`false`	`"other"`	`["new", "other"]`

Python

payload = {
    "sku": "12345678901234",
    "model": "ShipToolkit-001",
    "title": "Walmart fulfillment label",
    "madeIn": "China",
    "productCondition": "new",
    "labelSize": "2.25x1.25",
}
post_pdf("/v1/labels/walmart-sku", payload, "walmart-sku.pdf")

Java

String json = """
{
  "sku": "12345678901234",
  "model": "ShipToolkit-001",
  "title": "Walmart fulfillment label",
  "madeIn": "China",
  "productCondition": "new",
  "labelSize": "2.25x1.25"
}
""";
ShipToolkitApi.postPdf(
    "/v1/labels/walmart-sku",
    json,
    Path.of("walmart-sku.pdf")
);

POST /v1/labels/outbound-box

Create a compact outbound box label with a box barcode and item summary.

Field	Type	Required	Default	Constraints
`boxId`	`string`	`true`	`-`	`maxLength: 80`
`organization`	`string`	`true`	`-`	`maxLength: 160`
`items`	`array<object>`	`true`	`-`	`maxItems: 200`
`items[].sku`	`string`	`false`	`items[].model`	`maxLength: 128`
`items[].quantity`	`string\|number`	`false`	`items[].qty`	`maxLength: 20`
`dimension`	`string`	`false`	`""`	`maxLength: 120`
`weight`	`string`	`false`	`""`	`maxLength: 120`
`labelSize`	`enum`	`false`	`"2.25x1.25"`	`standardLabelSize`
`createBarcode`	`boolean`	`false`	`true`	`-`
`barcodeValue`	`string`	`false`	`boxId`	`maxLength: 80`

Python

payload = {
    "boxId": "BOX-1001",
    "organization": "Example Seller",
    "dimension": "20 x 10 x 8 in",
    "weight": "15 lbs",
    "labelSize": "3.00x1.50",
    "createBarcode": true,
    "items": [
        {"sku": "X001ABC123", "quantity": 4},
        {"sku": "X001ABC456", "quantity": 2},
    ],
}
post_pdf("/v1/labels/outbound-box", payload, "outbound-box.pdf")

Java

String json = """
{
  "boxId": "BOX-1001",
  "organization": "Example Seller",
  "dimension": "20 x 10 x 8 in",
  "weight": "15 lbs",
  "labelSize": "3.00x1.50",
  "createBarcode": true,
  "items": [
    {"sku": "X001ABC123", "quantity": 4},
    {"sku": "X001ABC456", "quantity": 2}
  ]
}
""";
ShipToolkitApi.postPdf(
    "/v1/labels/outbound-box",
    json,
    Path.of("outbound-box.pdf")
);

POST /v1/labels/carton-mark

Create carton mark labels with one page for each carton.

Field	Type	Required	Default	Constraints
`consignee`	`string`	`true`	`-`	`maxLength: 120`
`shipper`	`string`	`true`	`-`	`maxLength: 120`
`destinationAddress`	`string`	`true`	`-`	`maxLength: 500`
`orderNo`	`string`	`true`	`-`	`maxLength: 80`
`cartonTotal`	`integer`	`true`	`-`	`min: 1`
`quantity`	`string\|number`	`true`	`-`	`maxLength: 80`
`productDescription`	`string`	`true`	`-`	`maxLength: 500`
`labelSize`	`enum`	`false`	`"6x4"`	`cartonMarkLabelSize`
`barcodeValue`	`string`	`false`	`orderNo`	`maxLength: 120`
`cartonStart`	`integer`	`false`	`1`	`min: 1`

Python

payload = {
    "consignee": "Receiving Team",
    "shipper": "Example Seller",
    "destinationAddress": "123 Warehouse Way, Newark, DE 19713",
    "orderNo": "PO-20260717-001",
    "cartonTotal": 3,
    "quantity": "50 PCS",
    "productDescription": "Portable night light",
    "labelSize": "6x4",
}
post_pdf("/v1/labels/carton-mark", payload, "carton-mark.pdf")

Java

String json = """
{
  "consignee": "Receiving Team",
  "shipper": "Example Seller",
  "destinationAddress": "123 Warehouse Way, Newark, DE 19713",
  "orderNo": "PO-20260717-001",
  "cartonTotal": 3,
  "quantity": "50 PCS",
  "productDescription": "Portable night light",
  "labelSize": "6x4"
}
""";
ShipToolkitApi.postPdf(
    "/v1/labels/carton-mark",
    json,
    Path.of("carton-mark.pdf")
);

POST /v1/labels/transparency

Customize Amazon Transparency label PDFs with FNSKU, model, date, and target label size.

Field	Type	Required	Default	Constraints
`pdfBase64`	`string`	`true`	`-`	`maxBytes: 7MB`
`fnsku`	`string`	`true`	`-`	`maxLength: 80`
`labelSize`	`enum`	`true`	`-`	`standardLabelSize`
`model`	`string`	`false`	`""`	`maxLength: 240`
`date`	`string`	`false`	`now`	`maxLength: 40`

Python

payload = {
    "pdfBase64": pdf_base64("transparency-source.pdf"),
    "fnsku": "X001ABC123",
    "model": "MODEL-1",
    "date": "2026-07-17",
    "labelSize": "2.25x1.25",
}
post_pdf("/v1/labels/transparency", payload, "transparency.pdf")

Java

String source = ShipToolkitApi.pdfBase64(Path.of("transparency-source.pdf"));
String json = """
{
  "pdfBase64": "%s",
  "fnsku": "X001ABC123",
  "model": "MODEL-1",
  "date": "2026-07-17",
  "labelSize": "2.25x1.25"
}
""".formatted(source);
ShipToolkitApi.postPdf(
    "/v1/labels/transparency",
    json,
    Path.of("transparency.pdf")
);

PDF APIs

These endpoints return transformed PDF files and require a bearer API key.

POST /v1/pdf/resize

Resize every page to a preset or custom page size without cropping source content.

Field	Type	Required	Default	Constraints
`pdfBase64`	`string`	`true`	`-`	`maxBytes: 7MB`
`filename`	`string`	`false`	`"document.pdf"`	`maxLength: 160`
`size`	`enum`	`false`	`"letter"`	`"letter"\|"legal"\|"a4"\|"4x6"\|"custom"`
`orientation`	`enum`	`false`	`"match"`	`"match"\|"portrait"\|"landscape"`
`customWidth`	`number`	`false`	`-`	`required when size="custom"`
`customHeight`	`number`	`false`	`-`	`required when size="custom"`
`customUnit`	`enum`	`false`	`"in"`	`"in"\|"mm"`

Python

payload = {
    "pdfBase64": pdf_base64("source.pdf"),
    "filename": "source.pdf",
    "size": "custom",
    "customWidth": 2.25,
    "customHeight": 1.25,
    "customUnit": "in",
}
post_pdf("/v1/pdf/resize", payload, "resized.pdf")

Java

String source = ShipToolkitApi.pdfBase64(Path.of("source.pdf"));
String json = """
{
  "pdfBase64": "%s",
  "filename": "source.pdf",
  "size": "custom",
  "customWidth": 2.25,
  "customHeight": 1.25,
  "customUnit": "in"
}
""".formatted(source);
ShipToolkitApi.postPdf("/v1/pdf/resize", json, Path.of("resized.pdf"));

POST /v1/pdf/scale

Scale page content around the center while keeping each page size unchanged.

Field	Type	Required	Default	Constraints
`pdfBase64`	`string`	`true`	`-`	`maxBytes: 7MB`
`filename`	`string`	`false`	`"document.pdf"`	`maxLength: 160`
`scalePercent`	`number`	`false`	`100`	`min: 1, max: 400`

Python

payload = {
    "pdfBase64": pdf_base64("source.pdf"),
    "filename": "source.pdf",
    "scalePercent": 82,
}
post_pdf("/v1/pdf/scale", payload, "scaled.pdf")

Java

String source = ShipToolkitApi.pdfBase64(Path.of("source.pdf"));
String json = """
{
  "pdfBase64": "%s",
  "filename": "source.pdf",
  "scalePercent": 82
}
""".formatted(source);
ShipToolkitApi.postPdf("/v1/pdf/scale", json, Path.of("scaled.pdf"));