Skip to main content

​
API Reference and Rate Limiting

​
Authentication Methods

ORBEXA supports three authentication methods:

​
API Key Authentication

Used for MCP tool calls and API access: 
Authorization: Bearer YOUR_API_KEY
API keys are automatically generated when a merchant connects, and can also be created and managed manually in the console.

​
OAuth Authentication

Used for platform integrations such as Shopify, following the standard OAuth 2.0 flow.

​
Plugin Header Authentication

Used for WordPress plugin integration, requiring the following headers:
  • X-Plugin-Platform — Platform identifier
  • X-Plugin-Version — Plugin version number

​
Complete Endpoint Catalog

​
UCP Endpoints

EndpointMethodAuthDescription
/.well-known/ucpGETNoneUCP discovery document
/ucp/v1/productsGETAPI KeyProduct listing (JSON/TSV)
/ucp/v1/products/:idGETAPI KeyProduct details (with variants)
/ucp/v1/searchGETAPI KeyFull-text product search
/ucp/v1/checkout-sessionsPOSTAPI KeyCreate checkout session
/ucp/v1/manifestGETAPI KeyMerchant capability declaration
/ucp/acp-feed.jsonGETAPI KeyACP-formatted product feed

​
ACP Endpoints — JSON-RPC 2.0

MethodAuthDescription
commerce.searchAPI KeyProduct search
commerce.productAPI KeyProduct details
commerce.checkoutAPI KeyInitiate checkout
commerce.order_statusAPI KeyOrder status query
commerce.capabilitiesAPI KeyCapability declaration

​
ACP Endpoints — REST

EndpointMethodAuthDescription
/acp/v1/productsGETAPI KeyProduct listing
/acp/v1/checkoutPOSTAPI KeyCheckout operation

​
MCP Endpoints

EndpointMethodAuthDescription
/api/mcp/toolsGETAPI KeyTool listing
/api/mcp/executePOSTAPI KeyExecute tool
/api/mcp/resourcesGETAPI KeyResource listing
/api/mcp/usageGETAPI KeyUsage statistics
/api/mcp/promptsGETAPI KeyPrompt listing

​
Discovery Endpoints

EndpointMethodAuthDescription
/.well-known/ucpGETNoneUCP protocol discovery
/.well-known/acpGETNoneACP protocol discovery
/.well-known/mcpGETNoneMCP protocol discovery

​
OTR Endpoints

EndpointMethodAuthDescription
/api/otr/verify/:domainGETNoneQuery domain trust score
/.well-known/otr/verifyGETNoneStandardized trust query endpoint

​
Shopify Integration

EndpointMethodAuthDescription
Shopify OAuth CallbackGETOAuthHandles Shopify authorization callback
Shopify WebhooksPOSTHMAC SignatureReceives Shopify event notifications

​
WooCommerce Integration

EndpointMethodAuthDescription
/api/integrations/woocommerce/connectPOSTAPI KeyConnect store
/api/integrations/woocommerce/testPOSTAPI KeyTest connection
/api/integrations/woocommerce/sync/productsPOSTAPI KeySync products
/api/integrations/woocommerce/sync/ordersPOSTAPI KeySync orders
/api/integrations/woocommerce/sync/inventoryPOSTAPI KeySync inventory
/api/integrations/woocommerce/webhooks/setupPOSTAPI KeyRegister Webhooks
/api/integrations/woocommerce/webhooks/handlePOSTSignature VerificationHandle Webhook events

​
WordPress Integration

EndpointMethodAuthDescription
/api/integrations/wordpress/connectPOSTHeader AuthOne-click connection
/api/integrations/wordpress/statusPOSTHeader AuthQuery status
/api/integrations/wordpress/disconnectPOSTHeader AuthDisconnect

​
Rate Limiting Policies

ORBEXA enforces tiered rate limiting to ensure fair usage and platform stability:
Endpoint TypeRate LimitNotes
UCP endpoints100 req/minPrimary access point for AI agents
API endpoints60 req/minGeneral API calls
Auth endpoints10 req/minSensitive operations like login/registration
Webhook endpoints200 req/minReceiving platform event notifications
WordPress plugin3 req/min/IPPlugin connection and status queries
When rate limits are exceeded, the API returns HTTP 429 status codes. Clients should implement exponential backoff retry strategies.

​
Error Handling

​
Rate Limit Errors

When a request exceeds the rate limit, the API returns HTTP 429 status code: 
{
  "error": "rate_limit_exceeded",
  "retry_after": 30
}
The retry_after field indicates the number of seconds the client should wait before retrying.

​
Authentication Errors

Status CodeErrorDescription
401unauthorizedMissing or invalid authentication credentials
403forbiddenValid credentials but no access to the requested resource

​
General Errors

Status CodeErrorDescription
400bad_requestInvalid request parameters
404not_foundResource does not exist
500internal_errorInternal server error

​
Summary

ORBEXA provides a comprehensive API endpoint system covering the three major protocols (UCP/ACP/MCP), OTR trust queries, three platform integrations, and discovery endpoints. The rate limiting system applies tiered policies by endpoint type to ensure fair usage and platform stability.
Next chapter: Merchant Dashboard — KPI monitoring, integration management, data quality, and team permissions