Partner API

Build on TerraVault

Connect your ERP, POS, or supply chain systems directly to the hemp & cannabis marketplace. Full REST API with webhooks, scoped permissions, and real-time data.

Authentication

All API requests require a Bearer token in the Authorization header. API keys are scoped to specific permissions and rate-limited to 100 requests per minute.

Example request

curl -X GET https://terravault.app/api/v1/products \
  -H "Authorization: Bearer tv_live_k3x9m2..." \
  -H "Content-Type: application/json"

API keys are hashed with SHA-256 before storage. Keep your key secret — if compromised, rotate it immediately from the dashboard.

Endpoints

Core REST endpoints for managing products, search, inventory, and documents.

GET/api/v1/productsList products with filtering, pagination, and sorting

POST/api/v1/productsCreate a new product listing

PUT/api/v1/productsUpdate an existing product

GET/api/map-listingsSearch products by map viewport bounds

GET/api/searchFull-text search across all products and vendors

POST/api/inventoryRecord an inventory event (restock, sale, adjustment)

GET/api/documentsList documents (COAs, licenses, invoices)

Webhooks

Subscribe to real-time events. All payloads are signed with HMAC-SHA256 for verification. Failed deliveries are retried with exponential backoff (up to 8 attempts over 24 hours).

order.created

order.confirmed

order.shipped

order.delivered

order.disputed

product.created

product.updated

inventory.low_stock

document.expiring

Example webhook payload

{
  "id": "evt_a1b2c3d4e5",
  "type": "order.confirmed",
  "created_at": "2026-04-04T14:30:00Z",
  "data": {
    "order_id": "ord_x7y8z9",
    "buyer_id": "usr_abc123",
    "seller_id": "usr_def456",
    "total_cents": 425000,
    "currency": "USD",
    "items": [
      {
        "product_id": "prod_gh789",
        "name": "Indoor Flower — Cherry Diesel",
        "quantity_lbs": 50,
        "unit_price_cents": 8500
      }
    ]
  },
  "signature": "sha256=9f86d08..."
}

Permissions

API keys are scoped to specific permissions. Request only the scopes your integration needs.

Scope	Description
`products:read`	List and view product details
`products:write`	Create, update, and delete products
`orders:read`	View order history and status
`orders:write`	Create and manage orders
`inventory:read`	View inventory levels and events
`inventory:write`	Record inventory adjustments
`webhooks:manage`	Create, update, and delete webhook subscriptions

Ready to integrate?

Get your API key and start building on TerraVault today.

Get Your API Key Trust & Security