Shipping Labels API quickstart

Use this page for your first day with the API. The full integration guide has the complete request shapes, response fields, and error reference.

0. Before you start

Create your own credentials in Developer Settings > API credentials and keep the secret on your server. Gearment enables Shipping Labels on your account; you do not need to request it. GET /carriers-services (step 1) lists USPS in data once it is enabled. Only if data is empty, email integration@gearment.com with the email address of your Gearment account.

1. Authenticate

Set your credentials as server-side environment variables:

export GEARMENT_KEY='<your client key>'
export GEARMENT_SECRET='<your client secret>'
export GEARMENT_SHIPPING_URL='https://apiv2.gearment.com/integration-handler/api/v3/shipping'

Send both headers on every call:

curl "$GEARMENT_SHIPPING_URL/carriers-services" \
  -H "X-Gearment-Client-Key: $GEARMENT_KEY" \
  -H "X-Gearment-Client-Secret: $GEARMENT_SECRET"

The response lists the carriers your account can use. Today, wallet-billed purchases support USPS only.

2. Fund the wallet

In the dashboard, open Payments > Payment method. In the G-Wallet card, select Top-up, choose a funding method offered to your account in the Top-up dialog, follow the on-screen instructions, and select Next to submit the top-up. The G-Wallet card shows your current balance; Top-up history and Payments > Transaction history show your activity. If the dashboard asks you to verify your email or complete legal information, do that before continuing. Labels are charged only to your G-Wallet balance. Check what a purchase can use with the API:

curl "https://apiv2.gearment.com/integration-handler/api/v3/wallet" \
  -H "X-Gearment-Client-Key: $GEARMENT_KEY" \
  -H "X-Gearment-Client-Secret: $GEARMENT_SECRET"

data.available is the amount a new purchase can use.

The purchase refuses insufficient funds before buying a label. Its message contains label purchase funds insufficient, and that label ends as SELLER_LABEL_STATUS_FAILED. Add funds, then get a new quote and buy with a new request_id.

3. Quote

Save this as quote.json, replacing the example addresses and package details with the real shipment:

{
  "ship_from": {
    "first_name": "Warehouse",
    "last_name": "Team",
    "company": "Your Company",
    "phone_no": "7135550100",
    "email": "shipping@example.com",
    "street1": "2401 Polk St",
    "city": "Houston",
    "state_code": "TX",
    "zip_code": "77003",
    "country_code": "US"
  },
  "ship_to": {
    "first_name": "Jane",
    "last_name": "Buyer",
    "phone_no": "2135550100",
    "email": "jane.buyer@example.com",
    "street1": "727 S Broadway",
    "city": "Los Angeles",
    "state_code": "CA",
    "zip_code": "90014",
    "country_code": "US"
  },
  "package": {
    "weight": { "value": "8", "unit": "oz" },
    "dimensions": {
      "length": { "value": "10", "unit": "in" },
      "width": { "value": "8", "unit": "in" },
      "height": { "value": "1", "unit": "in" }
    },
    "value": { "currency_code": "USD", "units": "4", "nanos": 80 },
    "quantity": "1"
  }
}

curl -X POST "$GEARMENT_SHIPPING_URL/rates" \
  -H "X-Gearment-Client-Key: $GEARMENT_KEY" \
  -H "X-Gearment-Client-Secret: $GEARMENT_SECRET" \
  -H "Content-Type: application/json" \
  --data @quote.json

Choose a returned rate_id before its 15-minute expiry. Keep the exact shipment data from quote.json for the purchase.

4. Buy

Create purchase.json with the selected rate_id, a stable request ID, and the same shipment data:

{
  "request_id": "your-order-id-label-1",
  "rate_id": "srate_...",
  "label_format": "pdf",
  "ship_from": {
    "first_name": "Warehouse",
    "last_name": "Team",
    "company": "Your Company",
    "phone_no": "7135550100",
    "email": "shipping@example.com",
    "street1": "2401 Polk St",
    "city": "Houston",
    "state_code": "TX",
    "zip_code": "77003",
    "country_code": "US"
  },
  "ship_to": {
    "first_name": "Jane",
    "last_name": "Buyer",
    "phone_no": "2135550100",
    "email": "jane.buyer@example.com",
    "street1": "727 S Broadway",
    "city": "Los Angeles",
    "state_code": "CA",
    "zip_code": "90014",
    "country_code": "US"
  },
  "package": {
    "weight": { "value": "8", "unit": "oz" },
    "dimensions": {
      "length": { "value": "10", "unit": "in" },
      "width": { "value": "8", "unit": "in" },
      "height": { "value": "1", "unit": "in" }
    },
    "value": { "currency_code": "USD", "units": "4", "nanos": 80 },
    "quantity": "1"
  }
}

curl -X POST "$GEARMENT_SHIPPING_URL/labels" \
  -H "X-Gearment-Client-Key: $GEARMENT_KEY" \
  -H "X-Gearment-Client-Secret: $GEARMENT_SECRET" \
  -H "Content-Type: application/json" \
  --data @purchase.json

Record the returned label_id, request_id, status, and label_url. Use the label only when status is SELLER_LABEL_STATUS_PURCHASED.

5. Fetch

curl "$GEARMENT_SHIPPING_URL/labels/slbl_..." \
  -H "X-Gearment-Client-Key: $GEARMENT_KEY" \
  -H "X-Gearment-Client-Secret: $GEARMENT_SECRET"

Use this call to check a purchasing, failed, or refunded label. Failed labels include failure_reason.

6. Void an unused purchased label

curl -X POST "$GEARMENT_SHIPPING_URL/labels/slbl_.../void" \
  -H "X-Gearment-Client-Key: $GEARMENT_KEY" \
  -H "X-Gearment-Client-Secret: $GEARMENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{}'

Void only a purchased label. The label enters SELLER_LABEL_STATUS_REFUND_PENDING; the wallet receives the credit only after confirmation.

7. Ten things that most often trip up integrations

nanos means cents: "units": "4", "nanos": 80 is $4.80, not $4.000000080.
Use only oz, lb, kg, or g for weight and in for every dimension. Unsupported units return HTTP 400.
Use a US address. state_code accepts 1 to 10 characters, and country_code accepts US or USA.
A quote expires after 15 minutes, and rates above your agreed maximum are not returned.
A purchase must use the exact addresses and package data from its quote. A mismatch returns HTTP 400.
Use one stable request_id per label. Repeating it with the same purchase is safe; reusing it for different purchase data returns HTTP 409.
Send lowercase pdf or zpl; an empty format means pdf. USPS supports both.
Your wallet is held at purchase and charged only when the label is confirmed. Fund it before buying.
HTTP 504 or HTTP 503 with SELLER_LABEL_ERROR_REASON_PURCHASE_OUTCOME_UNKNOWN does not mean a new purchase is safe. Retry with the same request_id or fetch the label; contact support if it remains SELLER_LABEL_STATUS_PURCHASING for more than one day.
A void is not an immediate refund. USPS confirmation usually takes 2 to 4 weeks and can take up to 30 days; a rejected refund leaves the charge in place.

For limits, refund outcomes, testing, and the full error table, see the full integration guide.