API Reference v2 — Suite Profit

Authentication

Machine-to-machine traffic uses OAuth 2.0 client credentials, scoped to a portfolio and one or more property codes. Tokens are issued per property so a leaked token cannot cross-contaminate the estate. Identity teams provisioning operators use SCIM 2.0 tokens against /scim/v2/; user-scoped endpoints (approvals, escalations) may be authenticated with a SAML assertion federated from Okta, Entra ID, or PingFederate.

Authorization: Bearer sp_live_portfolio_47b91cb3...
X-SuiteProfit-Portfolio: prt_motlawa_estates
X-SuiteProfit-Property: prop_gdansk_marina

Endpoints

Method	Path	Description
GET	`/portfolios`	List portfolios visible to the current OAuth client.
GET	`/portfolios/{id}`	Fetch a portfolio with its brand ceilings, SLA tier and audit-stream target.
GET	`/portfolios/{id}/properties`	List properties inside a portfolio, with Profitroom property codes and per-entity billing IDs.
POST	`/rate-decisions`	Publish a governed rate decision across one or more properties in the portfolio.
GET	`/rate-decisions/{id}/audit-trail`	Full immutable audit trail — proposer, approver, ceiling checks, Profitroom write receipts.
GET	`/guest-threads`	List cross-property guest conversations threaded on portfolio-level guest identity.
GET	`/reputation-alerts`	Reputation score drops flagged at the portfolio or per-brand ceiling.
GET	`/parity-alerts`	OTA parity breaches detected against the portfolio's approved rate floors.
POST	`/fiscal-batches`	Submit a fiscal batch (KSeF / FA(2)) covering multiple properties under a single VAT entity.
GET	`/operations-tasks`	List escalated operations tasks routed by SLA tier and property.

Example: publish a governed rate decision

curl -X POST https://api.suiteprofit.org/v2/rate-decisions \
  -H "Authorization: Bearer sp_live_portfolio_47b91cb3..." \
  -H "X-SuiteProfit-Portfolio: prt_motlawa_estates" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": ["prop_gdansk_marina", "prop_sopot_grand"],
    "room_type_code": "STDD",
    "date_range": { "from": "2026-08-14", "to": "2026-08-21" },
    "proposed_rate": { "currency": "EUR", "minor_units": 13400 },
    "governance": {
      "brand_ceiling_id": "brk_marina_flag",
      "approver_saml_subject": "revenue.director@motlawa.example",
      "justification": "Pace ahead 18% vs LY, Sopot Grand cluster."
    }
  }'

Response:

{
  "data": {
    "id": "rdc_a19f4b7d",
    "status": "published",
    "properties_written": ["prop_gdansk_marina", "prop_sopot_grand"],
    "audit_trail_url": "/rate-decisions/rdc_a19f4b7d/audit-trail",
    "profitroom_write_receipts": [
      { "property": "prop_gdansk_marina", "profitroom_ref": "PR-RM-2026-88412", "at": "2026-07-28T14:22:07Z" },
      { "property": "prop_sopot_grand", "profitroom_ref": "PR-RM-2026-88413", "at": "2026-07-28T14:22:07Z" }
    ]
  },
  "meta": {
    "portfolio_id": "prt_motlawa_estates",
    "sla_tier": "enterprise"
  }
}

Rate limits

Rate limits scale with the plan: Chain Starter 500 req/min per portfolio, Group 2000 req/min, Enterprise 5000 req/min per portfolio. Every response carries X-SuiteProfit-Ratelimit-Remaining and X-SuiteProfit-Ratelimit-Reset. See the rate limits reference for burst behaviour and SLA credit rules.

Portfolio scoping

Every endpoint is scoped to a portfolio through the X-SuiteProfit-Portfolio header. Per-property tokens further constrain the scope. Cross-portfolio calls are refused with 403 SP-AUTH-INSUFFICIENT-ROLE. Enterprise portfolios can define brand-level ceilings that gate every write; ceilings are enforced server-side before any Profitroom Suite handshake is attempted.

Audit stream to SIEM

Enterprise plans include an audit stream that mirrors every authenticated call, rate decision, SSO event and fiscal batch to a customer-owned SIEM (Splunk HEC, Elastic, Sumo, or S3+SQS). The stream is signed, ordered, and delivered with at-most-15-second lag. Retention on our side is 400 days; the customer stream is the system of record for compliance audits.

Request/response conventions

All datetimes are ISO-8601 in UTC. Property-local times are exposed as separate _local fields when relevant.
All monetary values include a currency code and a minor_units integer.
Pagination is cursor-based. Every list endpoint accepts limit (max 500 on Enterprise, 200 on Group) and cursor; responses include meta.next_cursor when more pages exist.
Idempotency: every write endpoint accepts an Idempotency-Key header. Replay window is 72 hours on Enterprise, 48 hours on other plans.

Deprecation policy

Endpoints marked deprecated in the response headers (X-SuiteProfit-Deprecated: true) will be removed no earlier than 18 months from the announcement date on Enterprise plans, 12 months elsewhere. Every deprecation is announced on the changelog and mirrored to the enterprise audit stream.