# Get/Search activity logs

Retrieves activity logs for all subscription-related events and changes in the authenticated shop. Activity logs provide a comprehensive audit trail of all subscription activities, changes, and system events.

What are Activity Logs?
Activity logs are detailed records of every action, event, and change that occurs within your subscription system. They capture who made the change, when it happened, what was changed, and the result of the operation. This provides full traceability and audit capabilities for compliance, debugging, and customer support.

Log Information Captured:
- Entity Information:
  - Entity ID: The specific subscription, billing attempt, or resource affected
  - Entity Type: Type of resource (subscription, billing attempt, plan, settings, etc.)
  - Event Type: Specific action performed (see Event Types below)
  - Event Source: Origin of the event (customer portal, merchant portal, API, system, etc.)

- Event Details:
  - Status: SUCCESS, FAILURE, or INFO
  - Timestamp: When the event occurred
  - Activity By: User or system that triggered the event
  - Client IP: IP address of the requester (if applicable)
  - Additional Info: Detailed JSON payload with before/after values and context

Entity Types:
- SUBSCRIPTION_BILLING_ATTEMPT - Billing and payment attempt events
- SUBSCRIPTION_CONTRACT_DETAILS - Subscription contract modifications
- SUBSCRIPTION_GROUP_PLAN - Subscription plan changes
- SHIPPING_PROFILE - Delivery profile and shipping updates
- CANCELLATION_MANAGEMENT - Subscription cancellation events
- DUNNING_MANAGEMENT - Payment retry and dunning activities
- PRODUCT_SWAP - Product replacement events
- FREQUENCY_SWAP - Billing/delivery frequency changes
- EMAIL_TEMPLATE - Email template modifications
- SHOP_INFO - Shop settings and configuration changes
- SUBSCRIPTION_WIDGET_SETTINGS - Widget configuration updates
- CUSTOMER_PORTAL_SETTINGS - Portal settings modifications
- SUBSCRIPTION_BUNDLING - Bundle and bundling rule changes

Event Sources:
- CUSTOMER_PORTAL - Changes made by subscribers through the customer portal
- MERCHANT_PORTAL - Changes made by merchants in the admin panel
- MERCHANT_EXTERNAL_API - Changes made via API by merchants or integrations
- SHOPIFY_EVENT - Events triggered by Shopify webhooks
- SHOPIFY_FLOW - Events triggered by Shopify Flow automations
- SYSTEM_EVENT - Automated system events (scheduled tasks, sync operations)
- MERCHANT_PORTAL_BULK_AUTOMATION - Bulk operations initiated from admin panel

Common Event Types:
- Subscription Changes: CONTRACT_PAUSED, CONTRACT_ACTIVATED, CONTRACT_CANCELLED, CONTRACT_CREATED
- Product Changes: PRODUCT_ADD, PRODUCT_REMOVE, PRODUCT_REPLACE, PRODUCT_QUANTITY_CHANGE, PRODUCT_PRICE_CHANGE
- Billing Changes: NEXT_BILLING_DATE_CHANGE, BILLING_INTERVAL_CHANGE, BILLING_ATTEMPT_TRIGGERED, BILLING_ATTEMPT_SKIPPED
- Delivery Changes: DELIVERY_INTERVAL_CHANGE, SHIPPING_ADDRESS_CHANGE, DELIVERY_METHOD_UPDATED
- Payment Changes: PAYMENT_METHOD_UPDATED, SWITCH_PAYMENT_METHODS
- Email Events: SEND_UPCOMING_ORDER_EMAIL, SEND_TRANSACTION_FAILED_EMAIL, SEND_SUBSCRIPTION_CREATED_EMAIL
- Discount Events: DISCOUNT_APPLIED, DISCOUNT_REMOVED, PRICING_POLICY_DISCOUNT_APPLIED
- One-Time Products: ONE_TIME_PURCHASE_PRODUCT_ADDED, ONE_TIME_PURCHASE_PRODUCT_REMOVED

Query Parameters and Filtering:

You can filter activity logs using query parameters. All filters support standard operations:
- equals - Exact match
- in - Match any value in list
- greaterThan, lessThan - Date range filtering
- contains - Partial text match

Example Filter Queries:

1. Get all failed billing attempts:
   ?entityType.equals=SUBSCRIPTION_BILLING_ATTEMPT&eventType.equals=BILLING_ATTEMPT_TRIGGERED&status.equals=FAILURE

2. Get all customer portal changes:
   ?eventSource.equals=CUSTOMER_PORTAL

3. Get logs for a specific subscription:
   ?entityId.equals=123456&entityType.equals=SUBSCRIPTION_CONTRACT_DETAILS

4. Get logs within date range:
   ?createAt.greaterThan=2024-01-01T00:00:00Z&createAt.lessThan=2024-01-31T23:59:59Z

5. Get all cancellation events:
   ?eventType.equals=CONTRACT_CANCELLED

6. Get all API-triggered changes:
   ?eventSource.equals=MERCHANT_EXTERNAL_API

Pagination:

Results are paginated. Use standard Spring Data pagination parameters:
- page - Page number (zero-indexed, default: 0)
- size - Page size (default: 20, max: 100)
- sort - Sort criteria (e.g., createAt,desc or id,asc)

Example: ?page=0&size=50&sort=createAt,desc

Use Cases:
- Audit and Compliance: Track all changes for regulatory compliance and internal auditing
- Customer Support: Review subscription history to troubleshoot customer issues
- Debugging: Investigate failed operations and system errors
- Analytics: Analyze customer behavior and subscription lifecycle patterns
- Reporting: Generate reports on subscription changes, cancellations, and modifications
- Integration Monitoring: Track API usage and automated workflow executions
- Security: Monitor for unusual activity patterns or unauthorized changes

Important Notes:
- Activity logs are immutable and cannot be modified or deleted via API
- Logs are retained according to your subscription plan's retention policy
- The additionalInfo field contains detailed JSON with event-specific context
- For large exports, consider using pagination and filtering to reduce data transfer
- Logs are scoped to your shop - you can only access logs for your own subscriptions
- System events may not have an activityBy value as they're automated

Response Headers:
- X-Total-Count - Total number of matching records
- Link - Pagination links (first, last, next, prev)

Authentication: Requires valid api_key query parameter with appropriate permissions

Endpoint: GET /api/external/v2/activity-logs
Version: 0.0.1

## Query parameters:

  - `api_key` (string, required)
    Your API Key

  - `criteria` (object, required)
    Activity Log Search Criteria

  - `pageable` (object, required)
    Pagination parameters (page number and size)
    Example: {"page":0,"size":10,"sort":["id,desc"]}

## Response 200 fields (application/json):

  - `id` (integer)

  - `shop` (string)

  - `entityId` (integer)

  - `entityType` (string)
    Enum: "SUBSCRIPTION_BILLING_ATTEMPT", "SUBSCRIPTION_CONTRACT_DETAILS", "SUBSCRIPTION_GROUP_PLAN", "SHIPPING_PROFILE", "CANCELLATION_MANAGEMENT", "DUNNING_MANAGEMENT", "PRODUCT_SWAP", "FREQUENCY_SWAP", "EMAIL_TEMPLATE", "SHOP_INFO", "SUBSCRIPTION_WIDGET_SETTINGS", "CUSTOMER_PORTAL_SETTINGS", "SUBSCRIPTION_BUNDLING", "BULK_AUTOMATION"

  - `eventSource` (string)
    Enum: "CUSTOMER_PORTAL", "MERCHANT_PORTAL", "SHOPIFY_EVENT", "SYSTEM_EVENT", "MERCHANT_PORTAL_BULK_AUTOMATION", "MERCHANT_EXTERNAL_API", "SHOPIFY_FLOW"

  - `eventType` (string)
    Enum: "NEXT_BILLING_DATE_CHANGE", "NEXT_BILLING_TIME_CHANGE", "BILLING_INTERVAL_CHANGE", "DELIVERY_INTERVAL_CHANGE", "BILLING_ATTEMPT_TRIGGERED", "BILLING_ATTEMPT_SKIPPED", "PRODUCT_ADD", "PRODUCT_REMOVE", "PRODUCT_REPLACE", "PRODUCT_QUANTITY_CHANGE", "PRODUCT_PRICE_CHANGE", "PRODUCT_PRICING_POLICY_CHANGE", "PRODUCT_SELLING_PLAN_CHANGE", "PRODUCT_DELETED_SYNC", "CONTRACT_PAUSED", "CONTRACT_ACTIVATED", "CONTRACT_CANCELLED", "DELIVERY_METHOD_UPDATED", "SYSTEM_UPDATED_DELIVERY_PRICE", "MANUAL_DELIVERY_PRICE_UPDATED", "DELIVERY_PRICE_OVERRIDE_CHANGED", "SHIPPING_ADDRESS_CHANGE", "SHIPPING_ADDRESS_CHANGE_SYNC", "SEND_SUBSCRIPTION_CREATED_EMAIL", "SEND_TRANSACTION_FAILED_EMAIL", "SEND_UPCOMING_ORDER_EMAIL", "SEND_EXPIRING_CREDIT_CARD_EMAIL", "SEND_SHIPPING_ADDRESS_UPDATED_EMAIL", "SEND_ORDER_FREQUENCY_UPDATED_EMAIL", "SEND_NEXT_ORDER_DATE_UPDATED_EMAIL", "SEND_SUBSCRIPTION_PAUSED_EMAIL", "SEND_SUBSCRIPTION_CANCELED_EMAIL", "SEND_SUBSCRIPTION_RESUMED_EMAIL", "SEND_SUBSCRIPTION_PRODUCT_ADDED_EMAIL", "SEND_SUBSCRIPTION_PRODUCT_REMOVED_EMAIL", "SEND_SUBSCRIPTION_PRODUCT_REPLACED_EMAIL", "SEND_ORDER_SKIPPED_EMAIL", "ONE_TIME_PURCHASE_PRODUCT_ADDED", "ONE_TIME_PURCHASE_PRODUCT_REMOVED", "ONE_TIME_PURCHASE_PRODUCT_UPDATE", "SEND_SECURITY_CHALLENGE_EMAIL", "DISCOUNT_APPLIED", "DISCOUNT_REMOVED", "DUNNING_CANCELLED", "DUNNING_SKIPPED", "DUNNING_PAUSED", "DUNNING_ATTEMPT_SKIPPED", "BILLING_ATTEMPT_NOTIFICATION", "SEND_SUBSCRIPTION_MANAGEMENT_LINK", "PRICE_CHANGE_SYNC", "UPDATE_QUEUED_ATTEMPTS", "WEBHOOK", "SPLIT_CONTRACT", "SWITCH_PAYMENT_METHODS", "PAYMENT_METHOD_UPDATED", "SEND_OUT_OF_STOCK_EMAIL", "INFORMATIONAL_EVENT", "BULK_EMAIL", "CONTRACT_CREATED", "ANCHOR_DAY_REMOVED", "UPCOMING_ORDER_UPDATED", "SUBSCRIPTION_CONTRACT_UPDATED", "BILLING_ATTEMPT_UPDATED", "RESCHEDULE_FULFILLMENT", "FULFILLMENT_REFUNDED", "SWAP_AUTOMATION_TRIGGERED", "BAB_DISCOUNT_ADJUSTMENT", "BAB_PRODUCT_ADD", "BAB_PRODUCT_REMOVE", "BAB_QUANTITY_CHANGE", "STOP_UPCOMING_ORDER_EMAIL_UPDATED", "ORDER_TAGS_ADDED", "EMAIL", "SEND_TRANSACTION_SUCCESS_EMAIL", "TAGS_UPDATED", "SEND_PRODUCT_PRICE_UPDATED_EMAIL", "SUBSCRIPTION_GROUP_PLAN_UPDATE", "SUBSCRIPTION_GROUP_PLAN_CREATE", "SUBSCRIPTION_GROUP_PLAN_DELETE", "CREATED", "UPDATED", "SEND_SUSPENSION_EMAIL", "SEND_SUSPENSION_WARNING_EMAIL", "DELETED", "CURRENCY_MISMATCH_DETECTED", "PRICING_METHOD_APPLIED", "PRICING_POLICY_DISCOUNT_APPLIED", "PRICING_POLICY_SYNC_SKIPPED", "PRICING_POLICY_SYNC_FAILED", "PRICING_POLICY_NO_APPLICABLE_CYCLE", "PRICING_POLICY_REMOVED", "PRICING_POLICY_OVERRIDE", "AUTOMATIC_DISCOUNT_UPDATE", "BILLING_ATTEMPT_REFRESHED", "PRICE_CHANGE_SYNC_SKIPPED", "BASE_PRICE_CALCULATION", "LINE_DUTY_ADDED", "IMMEDIATE_RETRY_TRIGGERED", "PRICE_CHANGE_SYNC_BULK_AUTOMATION", "SCHEDULE_EXPIRING_CREDIT_CARD_EMAIL", "STARTED_BULK_AUTOMATION_PROCESSING", "DUPLICATE_BILLING_ATTEMPT_DETECTED", "AUTO_RESUME_SCHEDULED", "BILLING_CYCLE_PRODUCTS_SKIPPED", "ORDER_ATTRIBUTES_SYNCED", "DATE_ATTRIBUTE_MODIFIED_BEFORE_SYNC", "ORDER_DATE_SYNC_FAILED", "DELIVERY_DATE_SETTINGS_APPLIED"

  - `status` (string)
    Enum: "SUCCESS", "FAILURE", "INFO", "SKIPPED", "PARTIAL_FAILURE"

  - `createAt` (string)

  - `additionalInfo` (string)

  - `activityBy` (string)

  - `clientIp` (string)


## Response 400 fields

## Response 401 fields

## Response 403 fields

## Response 429 fields