Your shipping.
Your workflow.

01 / ACCESS

Start with a scoped key.

Sign in to your active customer account or verified ShipCove owner account, open API access, and create a key for your integration. Read permissions are selected by default. Add labels:write only when the integration should be allowed to purchase real postage, and labels:void only when it should request voids.

Save the key in a server environment variable or secret manager. It is displayed once. Never include it in frontend JavaScript, mobile app bundles, query strings, source control, or support messages. Browser requests with an Origin header are rejected; CORS access is not offered.

curl https://shipcove.net/api/v1/account \
  -H "Authorization: Bearer $SHIPCOVE_API_KEY"

Keys expire after the selected 30, 90, or 365 days, with 90 days as the default. Up to 5 active keys are available per workspace. Owner keys access the owner’s own shipments, not customer accounts. Create a replacement before expiry, update your server, then revoke the old key.

02 / QUOTE

Describe the actual packed package.

Send the shipment fields directly as JSON to POST /quotes, with Content-Type: application/json. The sample below is fictional: replace its addresses and measurements before requesting a quote.

{
  "from": {
    "name": "Example Warehouse",
    "line1": "123 Example St",
    "line2": "",
    "city": "Detroit",
    "state": "MI",
    "zip": "48201",
    "phone": "3135550100",
    "residential": false
  },
  "to": {
    "name": "Example Recipient",
    "line1": "456 Sample Ave",
    "line2": "",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90012",
    "phone": "",
    "residential": true
  },
  "pounds": 2,
  "ounces": 8,
  "length": 12,
  "width": 8,
  "height": 6,
  "reference": "ORDER-1042",
  "declaredValueCents": 0,
  "signature": "none",
  "packaging": "02",
  "contentsCategory": "general"
}

Weight must be above zero and no more than 150 lb in total. Ounces range from 0 to 15.99. Dimensions use positive whole inches, at most 108 inches per side; length plus girth cannot exceed 165 inches. The sender needs a valid phone number. UPS may adjust charges when actual measurements or delivery details differ.

The response includes id, rates, mode, and expiresAt (Unix milliseconds). Each rate contains a code, name, amount as a decimal string, and currency. Quotes normally expire after 10 minutes. Choose a returned service and use its exact customer price before its returned expiry. The API is for live shipping; quotes do not imply a free testing environment.

03 / PURCHASE

Confirm one exact label price.

Use POST /labels with the quote ID, a returned service code, confirmed: true, and maxAmountCents. Your maximum protects the customer from spending more than the amount your integration approved. Do not derive it from a competitor’s price or from the UPS account’s base cost.

curl https://shipcove.net/api/v1/labels \
  -X POST \
  -H "Authorization: Bearer $SHIPCOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-package-1" \
  --data '{"quoteId":"00000000-0000-4000-8000-000000000000","serviceCode":"03","confirmed":true,"maxAmountCents":1234}'

HTTP 201 indicates a newly ready purchase; 200 can return a ready result from a repeated request. HTTP 202 means the saved result is still processing or requires attention. Inspect status, error, and tracking; do not assume every successful HTTP response means a printable label exists.

The shipment id is your recovery reference. Save it alongside your order. Every physical package needs a separate label and tracking number. Create a separate quote and use a unique idempotency key for each new package; printing the same label twice does not purchase more postage.

04 / RECOVERY

Retry the action, not the purchase.

Purchases and voids require an Idempotency-Key: 8–128 characters, using letters, numbers, periods, underscores, colons, and hyphens. Keep the same key and identical request body when retrying the same action after a timeout. Reusing a key with different details is rejected.

1. Persist the action key and original request before sending a purchase.
2. After a timeout or HTTP 202, check GET /shipments/{id} when the ID is known. Retry the original POST with the same key and body if needed to recover its result.
3. If a result is uncertain or has an unresolved carrier outcome, stop and use ShipCove support. Do not request a replacement quote and buy again automatically.

For a void, send {"confirmed":true} to POST /shipments/{id}/void with a separate idempotency key. A void request is not proof of a UPS void. Wait for a confirmed result; used or ineligible labels may not be voidable.

05 / LABELS

Download the saved original.

GET /labels/{id} returns JSON containing image (base64) and format (the UPS image format). Decode the base64 using that format. This endpoint does not return a PDF or a UPS QR code. For 4×6 or Letter PDFs, use the ShipCove workspace’s print tools.

Do not crop barcodes or remove their quiet zones. Print at actual size and attach one unique label to each package. A download can remain unavailable until required high-value receipts are saved. Retrieve receipt metadata and download each required receipt; above $1,000 declared value, follow the UPS driver handoff and signed-receipt requirements shown in ShipCove.

Tracking reads return the saved snapshot and lastCheckedAt. Use the refresh endpoint to request a newer carrier result. This version does not provide tracking webhooks or proof-of-delivery downloads through the API.

REFERENCE / ROUTES

Endpoints and permissions.

List pagination uses nextCursor exactly as returned. Its current format is a creation timestamp and UUID separated by a period. Do not calculate your own cursor.

REFERENCE / OPERATIONS

Build for limits and clear failures.

General limits are 120 requests per key per minute and 240 per workspace per minute. Purchases, quotes, and tracking may have stricter operation or account limits. Honor the Retry-After response header on HTTP 429 and use bounded backoff.

{
  "error": {
    "code": "example_error",
    "message": "A safe explanation of the failed request.",
    "requestId": "request-reference"
  },
  "requestId": "request-reference"
}

Save the X-Request-Id header or JSON requestId when reporting an issue. Never log or send the Authorization header. Label files, customer addresses, and tracking details should be stored with access limited to authorized staff.