ShipSmarter API

The ShipSmarter REST API lets you create shipments, retrieve rates, and manage labels programmatically. All endpoints return JSON.

Authentication

All requests must be authenticated using an API key. Generate one from your API Access page. Pass the key in the Authorization header:

http

Authorization: Bearer ss_<prefix>_<secret>

Example:

bash

curl https://shipsmarter.vip/api/v1/shipments \
  -H "Authorization: Bearer ss_a1b2c3d4_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

Base URL

url

https://shipsmarter.vip/api/v1

Shipments

Create and manage shipments. Labels are generated automatically after creation.

Rates

Get shipping rate estimates before creating a shipment.

Webhooks

Register webhook endpoints from your API Access page. We will send an HTTP POST request to your URL when shipment events occur.

Events

Event	Description
`shipment.created`	A new shipment has been created
`shipment.label_created`	A label has been generated for the shipment
`shipment.status_changed`	The shipment status has changed
`shipment.cancelled`	The shipment has been cancelled

Payload Format

json

{
  "event": "shipment.label_created",
  "timestamp": 1709856000000,
  "data": {
    "id": 1234,
    "trackingNumber": "794644823917",
    "labelUrl": "https://cdn.shipsmarter.vip/labels/xxx.pdf",
    "status": "label_created"
  }
}

Signature Verification

Every webhook request includes an X-ShipSmarter-Signature header. Verify it to ensure the request came from ShipSmarter:

javascript

// Node.js example
const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with a message field.

Status	Meaning
`200`	Success
`201`	Created — resource was created successfully
`400`	Bad Request — missing or invalid parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — you don't have access to this resource
`404`	Not Found — the resource does not exist
`422`	Unprocessable — validation error (see message)
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — something went wrong on our end

json

// Error response format
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}