API Endpoints

Base URL

https://api.equos.one/e9v3

Machine-Readable Spec

The full API surface is described by an OpenAPI 3.1 specification at/openapi.yaml — import it into Postman, Insomnia, or an SDK generator. A ready-madePostman collection is also available, including the OAuth client-credentials token request.

Authentication

All endpoints require the following header:

Authorization: Bearer <token>

The token must have scope orders:write.

Rate Limiting

1 request/second per API key with a burst capacity of 10. The limit applies to all /e9v3 endpoints, including reads. See Rate Limiting for details.

Return & Transfer Orders

There are no dedicated endpoints for return and transfer orders. Instead, use the /sync endpoint with the appropriate orderType:

• Return orders: POST /sync with orderType: "returns" (the singular "return" is also accepted) and locationId
• Transfer orders: POST /sync with orderType: "transfer" and agentId

Contact Field Reference

Each order requires exactly one contact field. The table below shows an example contact field for each order type — /e9v3/orders/sync only enforces that exactly one of customerId, supplierId, locationId, or agentId is present, not which type pairs with which field:

{
  "success": true,
  "jobId": "inbound_1718000000000000000"
}

{
  "success": false,
  "error": "Validation failed",
  "details": [
    {
      "field": "items[0].sku",
      "message": "required field",
      "value": null
    },
    {
      "field": "items[0].quantity",
      "message": "must be greater than 0",
      "value": 0
    }
  ]
}

{
  "error": "invalid token"
}

{
  "error": "rate limit exceeded",
  "retry_after": 0.82,
  "rate_limit": "1 order/second",
  "burst_capacity": 10
}

{
  "success": false,
  "error": "Failed to queue order processing"
}

{
  "success": true,
  "jobId": "inbound_1718000000000000000"
}

{
  "success": false,
  "error": "Validation failed",
  "details": [
    {
      "field": "items[0].sku",
      "message": "required field",
      "value": null
    },
    {
      "field": "items[0].quantity",
      "message": "must be greater than 0",
      "value": 0
    }
  ]
}

{
  "error": "invalid token"
}

{
  "error": "rate limit exceeded",
  "retry_after": 0.82,
  "rate_limit": "1 order/second",
  "burst_capacity": 10
}

{
  "success": true,
  "jobId": "inbound_1718000000000000000"
}

{
  "success": false,
  "error": "Validation failed",
  "details": [
    {
      "field": "items[0].sku",
      "message": "required field",
      "value": null
    },
    {
      "field": "items[0].quantity",
      "message": "must be greater than 0",
      "value": 0
    }
  ]
}

{
  "error": "invalid token"
}

{
  "error": "rate limit exceeded",
  "retry_after": 0.82,
  "rate_limit": "1 order/second",
  "burst_capacity": 10
}

Reading Orders & Job Tracking

Supplier Match-or-Create Logic (Receive Orders)

When creating a receive order via POST /receive, if you don't provide a supplierId, the system will attempt to find or create a matching supplier contact.

Matching Precedence

The system searches for an existing supplier in this order:

1. External ID: If externalSupplierId is provided, match by externalId field (fastest)
2. Email: If supplierEmail is provided, match by email address
   • If multiple suppliers match → no match (ambiguous), continue to next method
3. Phone: If supplierPhone is provided, match by normalized phone (last 10 digits)
   • If multiple suppliers match → no match (ambiguous), continue to next method
4. Name: If supplierName is provided, match by business name or contact name
   • If multiple suppliers match → no match (ambiguous), continue to next method
5. Create New: If no match found, create a new supplier contact using provided details

Creating New Suppliers

When no match is found, the system creates a new supplier with:

• Required: At least supplierName (or supplierBusinessName if providing business entity)
• Optional: supplierAddressLine1, supplierAddressLine2, supplierSuburb, supplierState, supplierPostcode, supplierEmail, supplierPhone
• Link: externalSupplierId is stored for future matches on that ID

Date Format Reference

Order dates (orderDate, dispatchDate) must be provided in RFC 3339 format (ISO 8601 with timezone).

Acceptable formats:

• 2024-01-21T12:00:00Z — UTC (recommended)
• 2024-01-21T12:00:00+00:00 — UTC with explicit offset
• 2024-01-21T12:00:00-05:00 — Eastern Standard Time
• 2024-01-21T12:00:00.123Z — UTC with milliseconds

Important: Always include a timezone (Z for UTC or ±HH:MM offset). Dates without timezone information will be rejected.

Metadata Field Guidance

Both orders and line items support a metadata field for storing custom data:

• Type: Free-form JSON object (any valid JSON-serializable values)
• Keys: Must be strings (e.g., "department": "sales")
• Values: Can be strings, numbers, booleans, arrays, or nested objects
• Use cases: Track internal IDs, integration tags, cost centers, timestamps, or any custom attributes
• Persistence: Stored throughout the order processing lifecycle

Example:

"metadata": {
  "costCenter": "DEPT-42",
  "internalId": "order-12345",
  "tags": ["urgent", "vip"],
  "processedAt": "2024-01-21T12:00:00Z"
}

Common Validation Errors

Authentication Error Codes (401)

Permission Error Codes (403)

Job Result Schema

All order endpoints return a jobId and process asynchronously. Track the job's completion status using the job ID returned in the response.

Document Status Lifecycle: pending → processing → completed or failed

• Pending: Immediately after order creation
• Completed: When processing succeeds; includes result.orderId and completedAt timestamp
• Failed: When processing fails; includes an errorMessage string (there is no separate failedAt — the job keeps its createdAt)

See the Examples page for code to poll this document until job completion.

Contacts API

The contacts endpoints allow you to discover customers, suppliers, and other contacts in your account before creating orders. List and search read the published ContactIndex. Get-by-id reads the live contact document (full address, ABN, notes).

Authentication

All contacts endpoints require the contacts:read scope in your API key and Bearer token authentication.

Address Validation

List returns a contact when it has:

• At least one contact method: email, phone, or mobile
• Locality: suburb and postcode (street is optional on list)
• Valid postcode: postcode/suburb combination exists in the Australian postcode database (or the CSV was unavailable — then unverified)

List endpoint validation: Uses the Australian postcode database (fast, no network calls). addressStatus is postcode_only or unverified. Archived contacts and invalid postcodes are excluded. If no ContactIndex is published, list returns 404 "Contact index not published".

Single contact validation: Tries the address server (full address matching) first, then falls back to the postcode database. Returns the contact even when addressStatus is invalid.

List Contacts

GET /e9v3/contacts

Pages the published ContactIndex. Optional search filters by name, business name, or email. limit is a page size (default 100, max 500). Omit cursor for the first page — existing clients that only send search/limit still work. When hasMore is true, pass nextCursor as cursor to continue.

Query Parameters

• search (optional, string): Filter by contact name, business name, or email (case-insensitive)
• limit (optional, integer): Page size (default 100, max 500)
• cursor (optional, string): Previous page's nextCursor. Omit for the first page.

Example Request

GET /e9v3/contacts?search=acme&limit=100
Authorization: Bearer <jwt>

Example Response (200 OK)

{
  "success": true,
  "contacts": [
    {
      "contactId": "cust-123",
      "businessId": "biz-456",
      "name": "Acme Corporation",
      "businessName": "Acme Corporation",
      "email": "orders@acme.com",
      "phone": "+1-555-1234",
      "mobile": "+1-555-5678",
      "fax": "+1-555-9999",
      "website": "acme.com",
      "contactType": "customer",
      "status": "active",
      "priority": "high",
      "address": {
        "line1": "123 Main St",
        "line2": "Suite 200",
        "suburb": "Sydney",
        "state": "NSW",
        "postcode": "2000",
        "country": "Australia"
      },
      "business": {
        "abn": "12345678901",
        "acn": "987654321",
        "isGstRegistered": true
      },
      "metadata": {
        "notes": "Key account",
        "category": "wholesale",
        "tags": ["vip", "bulk-discount"],
        "createdAt": "2024-01-01T10:00:00Z",
        "updatedAt": "2024-01-15T14:30:00Z",
        "createdBy": "admin@equos.one",
        "updatedBy": "user@company.com"
      },
      "integration": {
        "externalId": "shopify-12345",
        "source": "shopify"
      },
      "addressStatus": "postcode_only"
    }
  ],
  "count": 1,
  "hasMore": false
}

Get Single Contact

GET /e9v3/contacts/:contactId

Retrieve full details for a specific contact by ID. Returns all contacts with full address validation details via the addressStatus field (uses addressr for full address matching when available).

Path Parameters

• contactId (required, string): The contact's unique identifier

Example Request

GET /e9v3/contacts/cust-123
Authorization: Bearer <jwt>

Example Response (200 OK)

{
  "success": true,
  "contacts": [
    {
      "contactId": "cust-123",
      "businessId": "biz-456",
      "name": "Acme Corporation",
      "businessName": "Acme Corporation",
      "email": "orders@acme.com",
      "phone": "+1-555-1234",
      "address": {
        "line1": "123 Main St",
        "suburb": "Sydney",
        "state": "NSW",
        "postcode": "2000",
        "country": "Australia"
      },
      "addressStatus": "validated"
    }
  ],
  "count": 1
}

Example Response (404 Not Found)

{
  "success": false,
  "error": "Contact not found",
  "count": 0
}

Contact Response Fields

All contact responses include the following structure:

Contact Fields

Address Validation Statuses

Address Object

Business Object

Metadata Object

Integration Object

Shopper Data API (GDPR)

Export or erase what EQUOS holds about one shopper, for Shopify's mandatory privacy webhooks (customers/data_request, customers/redact, shop/redact) or any equivalent request. Everything is limited to the key's business. Each call is synchronous, bounded, idempotent and writes one audit row (key, request id, which inputs were given, matched contact and order ids, statuses and counts; never the personal data).

Matching

Send at least one of externalRef, email, phone. Inputs are ORed; every matched contact is reported with matchedBy.

• externalRef: exact match of {provider}:{store}:customer:{id} (e.g. shopify:acme.myshopify.com:customer:7012345), the ref send-matched stores. Erased contacts keep a SHA-256 of the ref, so repeat calls by ref report already_erased.
• email: case-insensitive.
• phone: digits only, last 10 digits, AU +61 and 0 forms are equal. Fewer than 8 digits and 1300/1800/1900 numbers are rejected (400).

More than 25 matching contacts returns 422 and changes nothing. No match is a 200 (no_match / count: 0).

POST /e9v3/contacts/erase
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "externalRef": "shopify:acme.myshopify.com:customer:7012345",
  "email": "jordan.lee@example.com",
  "requestId": "shopify-webhook-5f0c",
  "reason": "customers/redact"
}

200 OK
{
  "success": true,
  "outcome": "erased",
  "requestId": "shopify-webhook-5f0c",
  "auditId": "813",
  "dryRun": false,
  "matched": 1,
  "contacts": [
    {
      "contactId": "con_8f3a2b1c",
      "matchedBy": ["email", "externalRef"],
      "status": "erased",
      "ordersMatched": 3,
      "ordersErased": 3,
      "ordersRemaining": false,
      "jobsScrubbed": 1,
      "jobsInFlight": 0,
      "refsRemoved": 1
    }
  ],
  "totals": { "contacts": 1, "ordersErased": 3, "jobsScrubbed": 1, "webhookLogsRedacted": 4, "shopifyDeliveriesRedacted": 2 }
}

Inventory API

Read stock levels, and declare absolute on-hand quantities from an external source of truth.

Catalog API

Serve the published, quantity-free product feed for storefronts and static site generators — with feed-tier prices merged in by effective SKU.

Manufacturing API

Address API

Secure Documents API

Upload a document and get back a hosted, shareable link. Synchronous — returns the URL directly, with no job to poll.

{
  "document_url": "https://docs.equos.one/r/a1b2c3"
}