Integrations

The Integrations API lets you connect external accounting providers (e.g. QuickBooks Online), manage connection settings, and sync orders for bookkeeping. Orders are automatically synced when paid; use the manual sync endpoints for orders created before the integration was connected or to retry failed syncs.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/integrations/accounting/authorize	Secret	Get OAuth authorization URL
GET	/v1/integrations/accounting/callback	Secret	Handle OAuth callback
GET	/v1/integrations/accounting/status	Secret	Get connection status
POST	/v1/integrations/accounting/test	Secret	Test accounting connection
DELETE	/v1/integrations/accounting	Secret	Disconnect accounting integration
PATCH	/v1/integrations/accounting/settings	Secret	Update integration settings
POST	/v1/integrations/accounting/sync/{orderId}	Secret	Sync an order to accounting
POST	/v1/integrations/accounting/sync/{orderId}/retry	Secret	Retry a failed sync
GET	/v1/integrations/accounting/sync-log	Secret	List sync log entries

---

Get OAuth authorization URL

GET /v1/integrations/accounting/authorize

Returns an OAuth URL the merchant should visit to authorize the accounting provider connection. The URL includes a CSRF state token.

Request

curl https://api.hydrajs.dev/v1/integrations/accounting/authorize \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "authorize_url": "https://appcenter.intuit.com/connect/oauth2?client_id=...&state=oauth_..."
  }
}

---

Handle OAuth callback

GET /v1/integrations/accounting/callback

Receives the authorization code from the accounting provider, exchanges it for access and refresh tokens, and stores the connection. Called automatically after the merchant authorizes the app.

Query parameters

Parameter	Type	Description
code	string	Authorization code from the provider
realmId	string	Provider company/realm identifier
state	string	CSRF state token (must match stored)

Response 201

{
  "data": {
    "connected": true
  }
}

---

Get connection status

GET /v1/integrations/accounting/status

Returns the current accounting integration status. Never exposes raw tokens.

Request

curl https://api.hydrajs.dev/v1/integrations/accounting/status \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "connected": true,
    "provider": "quickbooks",
    "status": "connected",
    "company_name": "Acme Corp",
    "last_sync_at": "2026-09-08T14:30:00.000Z",
    "error_message": null
  }
}

The status field is one of: connected, expired, error, disconnected.

---

Test accounting connection

POST /v1/integrations/accounting/test

Validates the connection by calling the accounting provider API. Returns the company name if successful. Stores the company name in settings on success.

Request

curl -X POST https://api.hydrajs.dev/v1/integrations/accounting/test \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "valid": true,
    "company_name": "Acme Corp",
    "error": null
  }
}

---

Disconnect accounting integration

DELETE /v1/integrations/accounting

Removes the accounting integration and deletes stored credentials.

Request

curl -X DELETE https://api.hydrajs.dev/v1/integrations/accounting \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

No content.

---

Update integration settings

PATCH /v1/integrations/accounting/settings

Updates provider-specific settings for the accounting integration.

Body parameters

Parameter	Type	Description
income_account_id	string	Accounting provider income account ID (optional)
deposit_account_id	string	Accounting provider deposit account ID (optional)

Request

curl -X PATCH https://api.hydrajs.dev/v1/integrations/accounting/settings \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"income_account_id": "85", "deposit_account_id": "92"}'

Response 200

{
  "data": {
    "income_account_id": "85",
    "deposit_account_id": "92",
    "company_name": "Acme Corp"
  }
}

---

Sync order to accounting

POST /v1/integrations/accounting/sync/{orderId}

Manually syncs an order to the connected accounting provider. Creates the customer, invoice, and payment in the external system. Idempotent — re-syncing an already-synced order is a no-op.

Path parameters

Parameter	Type	Description
orderId	string	Order ID to sync (e.g. ord_abc123)

Request

curl -X POST https://api.hydrajs.dev/v1/integrations/accounting/sync/ord_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "success": true,
    "error": null
  }
}

---

Retry failed sync

POST /v1/integrations/accounting/sync/{orderId}/retry

Retries a previously failed accounting sync for an order. Clears the previous error and re-attempts the sync.

Path parameters

Parameter	Type	Description
orderId	string	Order ID to retry (e.g. ord_abc123)

Request

curl -X POST https://api.hydrajs.dev/v1/integrations/accounting/sync/ord_abc123/retry \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "success": true,
    "error": null
  }
}

---

List sync log

GET /v1/integrations/accounting/sync-log

Returns a paginated list of sync log entries showing the history of sync operations with their status, entity types, and any error messages.

Query parameters

Parameter	Type	Default	Description
limit	integer	20	Results per page (1–100)
cursor	string	–	Pagination cursor from a previous response
entity_type	string	–	Filter by entity: order, customer, payment
status	string	–	Filter by status: pending, synced, failed, skipped

Request

curl "https://api.hydrajs.dev/v1/integrations/accounting/sync-log?limit=10&status=failed" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": [
    {
      "id": "isync_abc123",
      "entity_type": "order",
      "entity_id": "ord_xyz789",
      "external_entity_type": "Invoice",
      "external_entity_id": "1234",
      "direction": "outbound",
      "status": "synced",
      "error_message": null,
      "retry_count": 0,
      "metadata": {
        "doc_number": "1042"
      },
      "created_at": "2026-09-08T14:30:00.000Z",
      "updated_at": "2026-09-08T14:30:01.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJ0IjoiMjAyNi0wOS0wOFQxNDozMDowMC4wMDBaIiwiaWQiOiJpc3luY19hYmMxMjMifQ==",
    "has_more": false,
    "total": 1
  }
}

---

Integration status object

Field	Type	Description
connected	boolean	Whether an accounting provider is currently connected
provider	string	Provider name (e.g. "quickbooks") or null
status	string	connected, expired, error, or disconnected
company_name	string	Company name from the provider, or null
last_sync_at	string	ISO 8601 timestamp of last successful sync, or null
error_message	string	Last error message, or null

Sync log entry object

Field	Type	Description
id	string	Sync log entry ID (isync_...)
entity_type	string	order, customer, or payment
entity_id	string	Hydra entity ID (e.g. ord_..., cus_...)
external_entity_type	string	Provider entity type (e.g. Invoice, Customer)
external_entity_id	string	Provider entity ID, or null
direction	string	Sync direction (outbound)
status	string	pending, synced, failed, or skipped
error_message	string	Error details if status is failed, or null
retry_count	integer	Number of retry attempts
metadata	object	Additional context (e.g. doc_number, sync_token)
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp