Business Connection API

Manage external partner store integration states and programmatic merchant disconnections.

Authentication & Scopes

All connection endpoints require a Bearer access token obtained via POST /v1/auth/token.

Get Connection Status — GET /v1/connection/status

Returns the current integration status, store identity, and connection timestamp for the authenticated business.

• Method: GET
• URL: https://api.heldsway.com/api/v1/connection/status
• Required Scope: connections:read
• Rate Limit: 120 requests/minute
• Subscription Gate: None (always accessible so partners can monitor connectivity even if subscription lapses)

Example Request

curl -X GET "https://api.heldsway.com/api/v1/connection/status" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

Success Response — HTTP 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "business_id": 42,
    "business_name": "Acme Rentals",
    "connection_status": "connected",
    "connected_at": "2026-03-15T14:22:00.000000Z",
    "updated_at": "2026-03-15T14:22:00.000000Z"
  }
}

Response Fields

Disconnect Business — POST /v1/connection/disconnect

Deactivates the business integration. After disconnection, the API token and key become unusable.

• Method: POST
• URL: https://api.heldsway.com/api/v1/connection/disconnect
• Required Scope: connections:write
• Rate Limit: 60 requests/minute

Request Body

Example Request

curl -X POST "https://api.heldsway.com/api/v1/connection/disconnect" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Merchant requested integration removal."
  }'

Success Response — HTTP 200 OK

{
  "success": true,
  "message": "Business disconnected successfully.",
  "data": null
}

Error Responses