Skip to main content

Event Subscriptions

Installed marketplace apps can subscribe to approved event types through the merchant app framework.

Implemented route family​

Current routes include:

  • GET /api/v1/merchant/apps/installations/{installationId}/event_subscription
  • POST /api/v1/merchant/apps/installations/{installationId}/event_subscription

Legacy-compatible merchant paths may also be available under api/merchant/apps/*.

What a subscription contains​

A merchant app event subscription includes:

  • installation identifier
  • enabled or disabled status
  • approved event types
  • optional filter JSON

Retrieve the current subscription​

GET /api/v1/merchant/apps/installations/{installationId}/event_subscription

If no subscription exists yet, the service returns a disabled default view for the installation.

Update a subscription​

POST /api/v1/merchant/apps/installations/{installationId}/event_subscription

Typical request fields include:

  • enabled
  • event_types
  • filters_json

Validation rules​

The backend validates:

  • installation ownership
  • event type membership in the allowed platform list
  • event type approval for the specific app
  • JSON validity for filters

Operational note​

This flow is merchant-scoped and tied to an existing app installation. It should not be documented as a generic public event bus subscription API.