API & development
Develop addon actions and event handlers
Declare staff actions, validate JSON input and implement idempotent event behavior with genuine premium rights.
About 2 min read
On this page
Addon API
Implement AddonModule::actions(): array, run(string $action, array $input): OperationResult and onEvent(string $event, array $payload): void. Return only the actions you actually implement. The staff addon workspace checks module-management access and protected confirmation; the addon must still validate its own fields and required business/settings capability.
Native modules use declared workspace/status or specific validated actions, rather than exposing arbitrary SQL or shell commands. For example Currency delegates save/preview operations to its central validated services; Offline Payments opens its existing workspace and reports status. Unknown actions must fail explicitly.
Events
Use the complete event directory. The five supported events are order.created, invoice.issued, invoice.payment_recorded, service.cancellation_requested and system.tick. Ignore unknown events, validate payload IDs and deduplicate durable work. Do not turn a cancellation request into provider deletion or treat a refund direction as incoming funds.
The dispatcher records load/handler failures separately. Safe diagnostics omit exception messages/payloads that might contain secrets. A cached object does not preserve permission after its extension changes or its premium rights are revoked.
Premium package binding
Premium addons add a signed orbit_addon object with format 1, product_code hoster and the actual registered addon UUID. Their minimum core must meet the accepted enforcement integration. They use the pinned release publisher and existing genuine main installation identity; there is no new activation key or editable bypass flag. See premium runtime rights.
Validate
Test permission-denied staff, invalid/unknown actions, disabled/revoked/tampered packages, exact repeated events, refund direction, cross-owner data and unavailable premium authority. Keep addon-owned data/migrations isolated. A signed addon is still privileged trusted software and needs review before running against real billing data.