> ## Documentation Index > Fetch the complete documentation index at: https://juo.dev/llms.txt > Use this file to discover all available pages before exploring further. # List events > Returns a list of events. ## OpenAPI ````yaml openapi-admin.json GET /events openapi: 3.1.0 info: title: Juo Admin API version: 1.0.0 description: >- Programmatic access to subscription management for merchants. ## Core Resources - **Subscriptions** — the central entity. Belongs to a Customer, contains Items (product variants) and Discounts. Lifecycle: `active` → `paused` or `cancelled`; `paused` → `active` or `cancelled`; `cancelled` → `active` (via reactivate). - **Items** — subscription items (product variants) (quantity, price, billing/delivery policies). - **Discounts** — applied to subscriptions by discount code or manually (percentage or fixed amount, targeting subscription items or shipping). - **Customers** — customers who own subscriptions and payment methods. - **Products / Variants** — catalog products and variants that can be assigned to subscription plans. - **Schedules** — a read-only projection of upcoming billing orders, derived from subscription state, active schedule adjustments, and triggered workflows. **Schedule adjustments never modify the subscription** — they apply changes to upcoming orders matching the specified criteria (by cycle, date, or both), which may cover one or more orders. For permanent changes (billing frequency, items, payment method, delivery address), update the subscription directly. - **Workflows** — interactive customer-facing flows (retention, dunning, onboarding). Contain Steps connected by Transitions and produce Runs on each execution. Supports A/B experiment steps. ## Authentication Every request requires: - `X-Juo-Admin-Api-Key` header — the merchant's Admin API key. - `X-Tenant-ID` header — the store identifier (myshopify domain, e.g. `my-store.myshopify.com`). servers: - url: https://api.juo.io/admin/v1 security: - AdminApiKey: [] - BearerToken: [] tags: - name: subscriptions description: >- Recurring billing agreements with customers. Manage lifecycle (pause, resume, cancel, reactivate), items, and discounts. - name: customers description: Customers who own subscriptions. Create and update customer records. - name: products description: >- Products and variants linked to subscription plans. Manage catalog and plan assignments. - name: schedules description: >- Read-only view of upcoming billing orders generated from subscription state, schedule adjustments, and workflows. Use schedule adjustments for targeted changes to upcoming orders (scoped by cycle number, date, or both) — they never alter the subscription itself. For permanent changes (billing frequency, items, payment method), update the subscription directly. - name: workflows description: >- Interactive customer-facing flows for retention, dunning, and onboarding. Define steps, publish, and track execution runs and experiments. - name: workflowRuns description: >- Workflow runs across all workflows — the record of what happened each time a customer went through a workflow. Filter by customer to see one customer's run history. - name: events description: >- What happened in the shop, in two streams. activity: everything that happened to subscribers (subscriptions, customers, orders, billing, workflow runs, logins, mail), whoever did it; actor.type says who (staff, customer, system, bulk-action, api, unknown; staff is the panel). audit: shop-level actions: settings, exports, API access, bulk-action jobs and workflow edits. Filter by stream in query. - name: analytics description: >- Time-series metrics over subscriptions, customers and orders. Read the metric catalog first: it states what each metric means, the approximations it carries, and which filters and group-by dimensions the metric will honour — an unsupported filter is a 400, not an empty result. paths: /events: get: tags: - events summary: List events description: >- Returns a paginated list of events for the shop, in two streams. activity: everything that happened to subscribers (subscriptions, customers, orders, billing, workflow runs, logins, mail), whoever did it; actor.type says who (staff, customer, system, bulk-action, api, unknown; staff is the panel). audit: shop-level actions: settings, exports, API access, bulk-action jobs and workflow edits. Both streams are listed unless query filters by stream. The cursor is the pair (occurredAt, id), newest first by default. parameters: - schema: minLength: 1 type: string in: query name: query required: false description: >- Search query. Terms are `field:value`; comparisons `field:>value`, `:<`, `:>=`, `:<=`. Quote values in single or double quotes unless they are only letters and digits, with single dots between them, or a UUID as a filter value. Combine terms with `AND` (binds tighter) and `OR`, group with parentheses, negate a term or group with `NOT` or a leading `-`. Fields: type, stream, occurredAt, category, severity, subscriptionId, customerId, owner.entity, owner.id, actor.type, actor.id, operationId. Example: `stream:audit AND occurredAt:>='2026-09-01'`. See [search query language](/docs/api-reference/admin/introduction#search-query-language) and the [field reference](/docs/api-reference/admin/events/resource#search-query-fields). Only type and occurredAt support comparisons; other fields support equality. Date-only values cover the shop-local day; timestamps require an offset. subscriptionId matches the row owner only and takes the subscription id, not its serial. owner.entity accepts any non-empty, case-sensitive stored name, including historical names; a name with no matching public events returns an empty page. Changing query restarts pagination. customerId includes the customer's subscriptions, orders, workflow runs, payment methods, refunds and chargebacks. actor.type: staff, customer, system, bulk-action, api, unknown. - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: >- See [pagination](/docs/api-reference/admin/introduction#pagination) for more details on how to paginate the results. - schema: minLength: 1 type: string in: query name: after required: false description: >- See [pagination](/docs/api-reference/admin/introduction#pagination) for more details on how to paginate the results. Use endCursor of the current page to read the page after it. - schema: minLength: 1 type: string in: query name: before required: false description: >- See [pagination](/docs/api-reference/admin/introduction#pagination) for more details on how to paginate the results. Use startCursor of the current page to read the page before it. - schema: default: occurredAt:desc,id:desc type: string enum: - occurredAt:asc,id:asc - occurredAt:desc,id:desc in: query name: sort required: false description: >- See [sorting](/docs/api-reference/admin/introduction#sorting) for more details on how to sort the results. Use occurredAt,id in that order, both asc or both desc. - $ref: '#/components/parameters/TenantHeader' responses: '200': description: Default Response content: application/json: schema: type: object properties: resource: type: string enum: - list hasNextPage: type: boolean hasPrevPage: type: boolean endCursor: type: - 'null' - string startCursor: type: - 'null' - string data: type: array items: $ref: '#/components/schemas/Event' required: - resource - hasNextPage - hasPrevPage - endCursor - startCursor - data '400': description: >- Bad request — invalid input or violated business rule (e.g., wrong subscription status for the requested operation). '401': description: Unauthorized — missing, expired, or invalid API key. '403': description: Forbidden — authenticated but not permitted to access this resource. '404': description: >- Not found — the resource does not exist or belongs to a different tenant. '422': description: >- Unprocessable entity — well-formed request that fails semantic validation. components: parameters: TenantHeader: name: X-Tenant-ID x-speakeasy-name-override: tenant x-speakeasy-globals-hidden: true in: header schema: type: string required: true description: >- Unique identifier of the tenant in the system (usually a store identifier) schemas: Event: oneOf: - allOf: - type: object properties: id: minLength: 1 type: string stream: description: >- activity: everything that happened to subscribers (subscriptions, customers, orders, billing, workflow runs, logins, mail), whoever did it; actor.type says who (staff, customer, system, bulk-action, api, unknown; staff is the panel). audit: shop-level actions: settings, exports, API access, bulk-action jobs and workflow edits. Fixed per type. type: string enum: - activity - audit category: minLength: 1 type: string severity: type: string enum: - info - problem occurredAt: format: date-time type: string owner: oneOf: - type: 'null' - type: object properties: entity: minLength: 1 description: >- Case-sensitive stored owner entity name, for example Subscription, Customer or Shop. Any returned name, including a historical one, can be used with the owner.entity equality filter. type: string id: minLength: 1 type: string required: - entity - id actor: type: object properties: type: type: string enum: - staff - customer - system - bulk-action - api - unknown id: minLength: 1 type: - 'null' - string name: minLength: 1 type: - 'null' - string source: minLength: 1 type: - 'null' - string required: - type - id - name - source operationId: minLength: 1 type: - 'null' - string subscriptionId: minLength: 1 type: - 'null' - string customerId: minLength: 1 type: - 'null' - string summary: minLength: 1 type: string required: - id - stream - category - severity - occurredAt - owner - actor - operationId - subscriptionId - customerId - summary - oneOf: - $ref: '#/components/schemas/EventPayload_subscription_paused' - $ref: '#/components/schemas/EventPayload_subscription_resumed' - $ref: '#/components/schemas/EventPayload_subscription_reactivated' - $ref: '#/components/schemas/EventPayload_subscription_cancelled' - $ref: '#/components/schemas/EventPayload_subscription_skipped' - $ref: >- #/components/schemas/EventPayload_subscription_next_billing_date_changed - $ref: >- #/components/schemas/EventPayload_subscription_payment_method_changed - $ref: >- #/components/schemas/EventPayload_subscription_delivery_address_changed - $ref: '#/components/schemas/EventPayload_customer_updated' - $ref: >- #/components/schemas/EventPayload_customer_payment_method_created - $ref: >- #/components/schemas/EventPayload_customer_payment_method_revoked - $ref: '#/components/schemas/EventPayload_customer_logged_in' - $ref: '#/components/schemas/EventPayload_customer_login_failed' - $ref: '#/components/schemas/EventPayload_settings_updated' - $ref: '#/components/schemas/EventPayload_export_created' - $ref: '#/components/schemas/EventPayload_api_access_granted' - $ref: '#/components/schemas/EventPayload_staff_data_access_spike' discriminator: propertyName: type mapping: subscription:paused: '#/components/schemas/EventPayload_subscription_paused' subscription:resumed: '#/components/schemas/EventPayload_subscription_resumed' subscription:reactivated: '#/components/schemas/EventPayload_subscription_reactivated' subscription:cancelled: '#/components/schemas/EventPayload_subscription_cancelled' subscription:skipped: '#/components/schemas/EventPayload_subscription_skipped' subscription:next-billing-date-changed: >- #/components/schemas/EventPayload_subscription_next_billing_date_changed subscription:payment-method-changed: >- #/components/schemas/EventPayload_subscription_payment_method_changed subscription:delivery-address-changed: >- #/components/schemas/EventPayload_subscription_delivery_address_changed customer:updated: '#/components/schemas/EventPayload_customer_updated' customer-payment-method:created: >- #/components/schemas/EventPayload_customer_payment_method_created customer-payment-method:revoked: >- #/components/schemas/EventPayload_customer_payment_method_revoked customer:logged-in: '#/components/schemas/EventPayload_customer_logged_in' customer:login-failed: '#/components/schemas/EventPayload_customer_login_failed' settings:updated: '#/components/schemas/EventPayload_settings_updated' export:created: '#/components/schemas/EventPayload_export_created' api-access:granted: '#/components/schemas/EventPayload_api_access_granted' staff:data-access-spike: '#/components/schemas/EventPayload_staff_data_access_spike' - type: object properties: id: minLength: 1 type: string stream: description: >- activity: everything that happened to subscribers (subscriptions, customers, orders, billing, workflow runs, logins, mail), whoever did it; actor.type says who (staff, customer, system, bulk-action, api, unknown; staff is the panel). audit: shop-level actions: settings, exports, API access, bulk-action jobs and workflow edits. Fixed per type. type: string enum: - activity - audit category: minLength: 1 type: string severity: type: string enum: - info - problem occurredAt: format: date-time type: string owner: oneOf: - type: 'null' - type: object properties: entity: minLength: 1 description: >- Case-sensitive stored owner entity name, for example Subscription, Customer or Shop. Any returned name, including a historical one, can be used with the owner.entity equality filter. type: string id: minLength: 1 type: string required: - entity - id actor: type: object properties: type: type: string enum: - staff - customer - system - bulk-action - api - unknown id: minLength: 1 type: - 'null' - string name: minLength: 1 type: - 'null' - string source: minLength: 1 type: - 'null' - string required: - type - id - name - source operationId: minLength: 1 type: - 'null' - string subscriptionId: minLength: 1 type: - 'null' - string customerId: minLength: 1 type: - 'null' - string summary: minLength: 1 type: string type: type: string enum: - api-access:granted - bulk-action:completed - bulk-action:created - bulk-action:workflow-started - chargeback:created - commitment:placed - customer-payment-method:created - customer-payment-method:revoked - customer-portal:event - customer:logged-in - customer:login-failed - customer:merged - customer:subscriber-status-changed - customer:updated - export:created - instant-order:placed - instant-order:voided - invoice:placed - mail:sent - order:draft-created - order:placed - order:placement-failed - refund:completed - refund:created - refund:failed - renewal:notification-sent - schedule-adjustment:created - schedule-adjustment:deleted - settings:updated - staff:data-access-spike - subscription:cancellation-flow/cancelled - subscription:cancellation-flow/recovered - subscription:cancellation-flow/retained - subscription:cancellation-flow/started - subscription:cancelled - subscription:chargeback-created - subscription:created - subscription:delivery-address-changed - subscription:discount-added - subscription:discount-code-applied - subscription:discount-free-shipping-applied - subscription:discount-removed - subscription:discount-updated - subscription:line-added - subscription:line-removed - subscription:line-updated - subscription:merged-from - subscription:merged-to - subscription:migrated - subscription:next-billing-date-changed - subscription:paused - subscription:payment-method-changed - subscription:purchased - subscription:reactivated - subscription:refund-completed - subscription:refund-created - subscription:refund-failed - subscription:renew-failed - subscription:renewed - subscription:resumed - subscription:skipped - subscription:split-from - subscription:split-to - subscription:update-failed - subscription:updated - workflow-run:cancelled - workflow-run:completed - workflow-run:customer-responded - workflow-run:experiment-completed - workflow-run:experiment-entered - workflow-run:failed - workflow-run:started - workflow-run:timed-out - workflow:archived - workflow:created - workflow:deleted - workflow:duplicated - workflow:experiment-concluded - workflow:published - workflow:updated payloadFormat: type: string enum: - legacy data: type: object additionalProperties: true required: - id - stream - category - severity - occurredAt - owner - actor - operationId - subscriptionId - customerId - summary - type - payloadFormat - data title: Event EventPayload_subscription_paused: type: object properties: type: type: string enum: - subscription:paused payloadFormat: type: string enum: - typed data: type: object properties: previousStatus: type: string required: - previousStatus required: - type - payloadFormat - data title: EventPayload_subscription_paused EventPayload_subscription_resumed: type: object properties: type: type: string enum: - subscription:resumed payloadFormat: type: string enum: - typed data: type: object properties: previousStatus: type: string required: - previousStatus required: - type - payloadFormat - data title: EventPayload_subscription_resumed EventPayload_subscription_reactivated: type: object properties: type: type: string enum: - subscription:reactivated payloadFormat: type: string enum: - typed data: type: object properties: previousStatus: type: string required: - previousStatus required: - type - payloadFormat - data title: EventPayload_subscription_reactivated EventPayload_subscription_cancelled: type: object properties: type: type: string enum: - subscription:cancelled payloadFormat: type: string enum: - typed data: type: object properties: previousStatus: type: string reason: type: - 'null' - string required: - previousStatus - reason required: - type - payloadFormat - data title: EventPayload_subscription_cancelled EventPayload_subscription_skipped: type: object properties: type: type: string enum: - subscription:skipped payloadFormat: type: string enum: - typed data: type: object properties: skippedDate: format: date-time type: string nextBillingDate: format: date-time type: string required: - skippedDate - nextBillingDate required: - type - payloadFormat - data title: EventPayload_subscription_skipped EventPayload_subscription_next_billing_date_changed: type: object properties: type: type: string enum: - subscription:next-billing-date-changed payloadFormat: type: string enum: - typed data: type: object properties: from: format: date-time type: string to: format: date-time type: string cause: type: string enum: - requested - skipped - resumed - reconciled required: - from - to - cause required: - type - payloadFormat - data title: EventPayload_subscription_next_billing_date_changed EventPayload_subscription_payment_method_changed: type: object properties: type: type: string enum: - subscription:payment-method-changed payloadFormat: type: string enum: - typed data: type: object properties: from: type: - 'null' - string to: type: - 'null' - string required: - from - to required: - type - payloadFormat - data title: EventPayload_subscription_payment_method_changed EventPayload_subscription_delivery_address_changed: type: object properties: type: type: string enum: - subscription:delivery-address-changed payloadFormat: type: string enum: - typed data: type: object properties: changedFields: type: array items: type: string required: - changedFields required: - type - payloadFormat - data title: EventPayload_subscription_delivery_address_changed EventPayload_customer_updated: type: object properties: type: type: string enum: - customer:updated payloadFormat: type: string enum: - typed data: type: object properties: changedFields: type: array items: type: string required: - changedFields required: - type - payloadFormat - data title: EventPayload_customer_updated EventPayload_customer_payment_method_created: type: object properties: type: type: string enum: - customer-payment-method:created payloadFormat: type: string enum: - typed data: type: object properties: paymentMethodId: type: string instrumentType: type: string cause: type: string required: - paymentMethodId - instrumentType required: - type - payloadFormat - data title: EventPayload_customer_payment_method_created EventPayload_customer_payment_method_revoked: type: object properties: type: type: string enum: - customer-payment-method:revoked payloadFormat: type: string enum: - typed data: type: object properties: paymentMethodId: type: string instrumentType: type: string cause: type: string required: - paymentMethodId - instrumentType required: - type - payloadFormat - data title: EventPayload_customer_payment_method_revoked EventPayload_customer_logged_in: type: object properties: type: type: string enum: - customer:logged-in payloadFormat: type: string enum: - typed data: type: object properties: method: type: string required: - method required: - type - payloadFormat - data title: EventPayload_customer_logged_in EventPayload_customer_login_failed: type: object properties: type: type: string enum: - customer:login-failed payloadFormat: type: string enum: - typed data: type: object properties: code: type: string required: - code required: - type - payloadFormat - data title: EventPayload_customer_login_failed EventPayload_settings_updated: type: object properties: type: type: string enum: - settings:updated payloadFormat: type: string enum: - typed data: type: object properties: changes: type: array items: anyOf: - type: object properties: path: type: string from: {} to: {} required: - path - from - to - type: object properties: path: type: string changed: type: boolean enum: - true required: - path - changed required: - changes required: - type - payloadFormat - data title: EventPayload_settings_updated EventPayload_export_created: type: object properties: type: type: string enum: - export:created payloadFormat: type: string enum: - typed data: type: object properties: resource: type: string enum: - subscriptions - customers - workflow-runs - metrics - products - retention-flow format: type: string enum: - csv - json rowCount: minimum: 0 type: integer status: type: string enum: - completed - failed - aborted filterFields: type: array items: type: string required: - resource - format - rowCount - status - filterFields required: - type - payloadFormat - data title: EventPayload_export_created EventPayload_api_access_granted: type: object properties: type: type: string enum: - api-access:granted payloadFormat: type: string enum: - typed data: type: object properties: source: type: string enum: - mcp - cli userId: type: string required: - source - userId required: - type - payloadFormat - data title: EventPayload_api_access_granted EventPayload_staff_data_access_spike: type: object properties: type: type: string enum: - staff:data-access-spike payloadFormat: type: string enum: - typed data: type: object properties: staffId: type: string window: type: string exports: minimum: 0 type: integer rowsExported: minimum: 0 type: integer threshold: minimum: 0 type: integer required: - staffId - window - exports - rowsExported - threshold required: - type - payloadFormat - data title: EventPayload_staff_data_access_spike securitySchemes: AdminApiKey: type: apiKey name: X-Juo-Admin-Api-Key in: header description: >- Long-lived Admin API key issued from the Juo merchant portal. Pass as the `X-Juo-Admin-Api-Key` header. BearerToken: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT minted via the merchant browser-session flow. Carries the authenticated staff identity so that API calls are attributed to the specific staff user in the activity log. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.