API Reference

Vectis provides a REST API for all operations. 70+ public endpoints, OpenAPI 3.1 documented, with HMAC-signed webhooks.

Base URL

https://api.vectisoms.app/v1

Authentication

All API requests require OAuth 2.0 authentication using the client credentials flow.

Getting an Access Token

curl -X POST https://api.vectisoms.app/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scope": "orders:read orders:write inventory:read"
  }'

Using the Token

Authorization: Bearer <access_token>

Available Scopes

Scope	Description
orders:read	Read orders
orders:write	Create and update orders
products:read	Read products
products:write	Create and update products
inventory:read	Read inventory levels
inventory:write	Update inventory levels
warehouses:read	Read warehouse information
warehouses:write	Manage warehouses
packages:read	Read package information
packages:write	Manage packages
returns:read	Read return requests
returns:write	Manage returns
webhooks:manage	Manage webhook subscriptions

Create OAuth credentials in Settings → API Access.

Common Endpoints

Orders

Method	Endpoint	Description
GET	/orders	List orders with filtering and pagination
GET	/orders/:id	Get order details
POST	/orders	Create an order
PATCH	/orders/:id	Update order
POST	/orders/:id/cancel	Cancel order
POST	/orders/:id/allocate	Allocate inventory
POST	/orders/:id/ship	Mark as shipped

Inventory

Method	Endpoint	Description
GET	/inventory	List inventory by warehouse/product
POST	/inventory/adjust	Adjust quantity with reason code
POST	/inventory/transfer	Transfer between locations
POST	/inventory/reserve	Reserve for an order
POST	/inventory/release	Release reservation

Products

Method	Endpoint	Description
GET	/products	List products
GET	/products/:id	Get product details
POST	/products	Create product
PATCH	/products/:id	Update product
DELETE	/products/:id	Delete product

Packages

Method	Endpoint	Description
GET	/packages	List packages
GET	/packages/:id	Get package details
POST	/packages/:id/ship	Generate label and ship
GET	/packages/:id/label	Download shipping label

Warehouses

Method	Endpoint	Description
GET	/warehouses	List warehouses
GET	/warehouses/:id	Get warehouse details
POST	/warehouses	Create warehouse
PATCH	/warehouses/:id	Update warehouse

Request Format

All requests use JSON:

POST /v1/orders
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "external_id": "SHOP-12345",
  "channel": "shopify",
  "items": [
    { "sku": "WIDGET-BLU", "quantity": 2, "price": 29.99 },
    { "sku": "GADGET-RED", "quantity": 1, "price": 49.99 }
  ],
  "ship_to": {
    "name": "John Doe",
    "address1": "123 Main St",
    "city": "Phoenix",
    "state": "AZ",
    "postal_code": "85001",
    "country": "US"
  }
}

Response Format

Successful responses return JSON with the resource:

{
  "id": "ord_abc123",
  "external_id": "SHOP-12345",
  "status": "pending",
  "items": [...],
  "created_at": "2026-01-15T10:30:00Z"
}

Errors return a consistent format:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid SKU: WIDGET-BLU not found",
    "field": "items[0].sku"
  }
}

Pagination

List endpoints support pagination:

GET /v1/orders?page=1&per_page=50

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 1234,
    "total_pages": 25
  }
}

Filtering

Filter by query parameters:

GET /v1/orders?status=pending&channel=shopify&created_after=2026-01-01

Webhooks

Configure webhooks in Settings → Webhooks. All webhooks are signed with HMAC-SHA256.

Verifying Signatures

const crypto = require('crypto');

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

Event Types

• order.created
• order.updated
• order.cancelled
• order.shipped
• package.created
• package.shipped
• package.delivered
• inventory.adjusted
• inventory.low_stock

Rate Limits

• Standard: 100 requests/minute
• Burst: 200 requests/minute (short bursts allowed)

Rate limit headers included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Idempotency

For POST requests, include an idempotency key:

Idempotency-Key: unique-request-id-12345

Duplicate requests with the same key return the original response.

OpenAPI Specification

Full OpenAPI 3.1 spec available at:

https://api.vectisoms.app/v1/openapi.json

Interactive Swagger UI at:

https://api.vectisoms.app/docs

SDKs

Official SDKs coming soon. For now, use any HTTP client with the REST API.

Support

• API questions: support@stoalogistics.com
• Bug reports: support@stoalogistics.com