Shipping API Test Environment

Test environment

This page documents the test environment. For production server-to-server integrations, use the Shipping Labels API guide.

Status: test environment. Use this endpoint for integration QA only. It does not buy a real label, debit a real wallet, or provide production acceptance evidence.

Base URL and authentication

The test route family is:

https://api-dev.gearmentinc.com/integration-handler/api/v3/shipping

Request a generated test client by emailing integration@gearment.com. Authenticate with the test client supplied by Gearment:

X-Gearment-Client-Key: YOUR_GEARMENT_CLIENT_KEY
X-Gearment-Client-Secret: YOUR_GEARMENT_CLIENT_SECRET
Content-Type: application/json

Test credentials are issued to an approved integration contact. Production credentials are not accepted by this test environment. After production activation, an authorized team administrator creates team-scoped credentials in Developer Settings > API credentials. Using a credential created in Developer Settings against api-dev.gearmentinc.com returns 401; use the generated test client only.

Operations

Method	Path	Purpose
GET	/carriers-services	Discover enabled carrier and service combinations.
POST	/rates	Request a rate quote for one shipment.
POST	/labels	Purchase a label or replay an existing request.
GET	/labels/{label_id}	Read an account-owned label.
POST	/labels/{label_id}/void	Request cancellation or refund.

The complete paths are prefixed with /integration-handler/api/v3/shipping. The authenticated credential determines the account; clients never send an account ID in the payload.

Money convention

nanos carries cents (0-99), not billionths of a dollar. For example, "units": "5", "nanos": 97 means $5.97 USD.

Create a rate quote

POST /integration-handler/api/v3/shipping/rates HTTP/1.1
Host: api-dev.gearmentinc.com
Content-Type: application/json
X-Gearment-Client-Key: YOUR_GEARMENT_CLIENT_KEY
X-Gearment-Client-Secret: YOUR_GEARMENT_CLIENT_SECRET

{
  "ship_from": {
    "street1": "100 Example Way",
    "city": "Los Angeles",
    "state_code": "CA",
    "zip_code": "90001",
    "country_code": "US",
    "first_name": "Example",
    "last_name": "Sender",
    "phone_no": "5555550100"
  },
  "ship_to": {
    "street1": "200 Example Street",
    "city": "New York",
    "state_code": "NY",
    "zip_code": "10001",
    "country_code": "US",
    "first_name": "Example",
    "last_name": "Recipient",
    "phone_no": "5555550101"
  },
  "package": {
    "dimensions": {
      "length": { "value": "10", "unit": "in" },
      "width": { "value": "8", "unit": "in" },
      "height": { "value": "1", "unit": "in" }
    },
    "weight": { "value": "8", "unit": "oz" },
    "value": { "currency_code": "USD", "units": "10", "nanos": 0 },
    "quantity": "1"
  }
}

{
  "request_id": "...",
  "status": "success",
  "message": "Shipping rates estimated",
  "data": {
    "rate_quote_id": "srq_...",
    "expires_at": "2026-09-10T14:18:22Z",
    "rates": [
      {
        "rate_id": "srate_...",
        "carrier": "USPS",
        "service": "GroundAdvantage",
        "delivery_days": 3,
        "seller_price": {
          "currency_code": "USD",
          "units": "5",
          "nanos": 97
        }
      }
    ]
  }
}

Purchase and retrieve a label

Use the selected rate_id, a unique request_id, and the same shipment data used to quote the shipment:

{
  "request_id": "your-shipment-id-label-1",
  "rate_id": "srate_...",
  "label_format": "pdf",
  "ship_from": {
    "street1": "100 Example Way",
    "city": "Los Angeles",
    "state_code": "CA",
    "zip_code": "90001",
    "country_code": "US",
    "first_name": "Example",
    "last_name": "Sender",
    "phone_no": "5555550100"
  },
  "ship_to": {
    "street1": "200 Example Street",
    "city": "New York",
    "state_code": "NY",
    "zip_code": "10001",
    "country_code": "US",
    "first_name": "Example",
    "last_name": "Recipient",
    "phone_no": "5555550101"
  },
  "package": {
    "dimensions": {
      "length": { "value": "10", "unit": "in" },
      "width": { "value": "8", "unit": "in" },
      "height": { "value": "1", "unit": "in" }
    },
    "weight": { "value": "8", "unit": "oz" },
    "value": { "currency_code": "USD", "units": "10", "nanos": 0 },
    "quantity": "1"
  }
}

POST /labels returns a label such as:

{
  "request_id": "...",
  "status": "success",
  "message": "Shipping label purchased",
  "data": {
    "label_id": "slbl_...",
    "request_id": "your-shipment-id-label-1",
    "status": "SELLER_LABEL_STATUS_PURCHASED",
    "billing_state": "SELLER_LABEL_BILLING_STATE_CHARGED",
    "rate_id": "srate_...",
    "carrier": "USPS",
    "service": "GroundAdvantage",
    "seller_price": {
      "currency_code": "USD",
      "units": "5",
      "nanos": 97
    },
    "tracking_no": "TRACKING_EXAMPLE_001",
    "tracking_url": "https://...",
    "label_url": "https://...",
    "label_format": "pdf",
    "created_at": "2026-09-10T14:06:01Z"
  }
}

Repeat the identical purchase payload to replay the same label. A changed payload with the same request_id must be treated as a conflict. Read a label with GET /labels/{label_id}. Request cancellation with POST /labels/{label_id}/void and poll GET until the provider result becomes terminal.

Test boundary

The test environment exercises the intended v3 partner route family and its request/response contract. Carrier and wallet state are synthetic, so its rates and refund outcomes are not production parity evidence. Production account enablement, real carrier behavior, production billing, and release remain separate gates.