# Activities

Point activities and transactions

## Get point transactions with pagination

> Retrieve paginated list of point transactions/activities

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Activities","description":"Point activities and transactions"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"PaginatedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"},"description":"Array of items for current page"},"meta":{"type":"object","properties":{"pagination":{"type":"object","required":["hasNext","hasPre"],"properties":{"hasNext":{"type":"boolean","description":"True if more results exist after current page"},"hasPre":{"type":"boolean","description":"True if results exist before current page"},"total":{"type":"integer","description":"Total count of all matching results (when available)"},"totalPage":{"type":"integer","description":"Total number of pages calculated as ceil(total/limit) (when available)"}}}},"description":"Pagination metadata container"}}}]},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Activity":{"type":"object","description":"Point transaction/activity with all fields that may be returned by the API. Note: Actual responses may only include non-null fields due to automatic filtering.","properties":{"id":{"type":"string","description":"Activity ID"},"shopId":{"type":"string","description":"Shop ID"},"customerId":{"type":"string","description":"Internal customer ID"},"shopifyCustomerId":{"type":"integer","description":"Shopify customer ID"},"email":{"type":"string","format":"email","description":"Customer email address"},"content":{"type":"string","description":"Activity description/content"},"type":{"type":"string","description":"Activity type"},"source":{"type":"string","description":"Source of the activity"},"event":{"type":"string","description":"Program event that triggered this activity"},"oldPoint":{"type":"integer","description":"Previous point balance"},"newPoint":{"type":"integer","description":"New point balance after this activity"},"programId":{"type":"string","nullable":true,"description":"Associated program ID"},"programTitle":{"type":"string","nullable":true,"description":"Associated program title"},"priceRuleId":{"type":"string","nullable":true,"description":"Shopify price rule ID for discounts"},"discountId":{"type":"string","nullable":true,"description":"Shopify discount ID"},"couponCode":{"type":"string","nullable":true,"description":"Generated coupon code"},"orderId":{"type":"string","nullable":true,"description":"Associated Shopify order ID"},"orderName":{"type":"string","nullable":true,"description":"Shopify order name"},"orderNumber":{"type":"integer","nullable":true,"description":"Shopify order number"},"orderCurrency":{"type":"string","nullable":true,"description":"Order currency code"},"earnBy":{"type":"string","nullable":true,"description":"How points were earned (price/order)"},"rateMoney":{"type":"number","nullable":true,"description":"Money to points conversion rate"},"earnPoint":{"type":"integer","nullable":true,"description":"Points earned in this activity"},"spendPoint":{"type":"integer","nullable":true,"description":"Points spent in this activity"},"referralCustomerEmail":{"type":"string","nullable":true,"description":"Email of referring customer"},"referredCustomerEmail":{"type":"string","nullable":true,"description":"Email of referred customer"},"milestoneOrder":{"type":"integer","nullable":true,"description":"Milestone order number"},"isPendingPointPlaceOrder":{"type":"boolean","nullable":true,"description":"Whether points are pending for order"},"refundPendingPoint":{"type":"integer","nullable":true,"description":"Refunded pending points"},"pendingPointUntil":{"type":"string","format":"date-time","nullable":true,"description":"When pending points expire"},"adminNote":{"type":"string","nullable":true,"description":"Admin note for this activity"},"userNote":{"type":"string","nullable":true,"description":"User note for this activity"},"reason":{"type":"string","nullable":true,"description":"Reason for the activity"},"createdAt":{"type":"string","format":"date-time","description":"Activity creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/rest_api/v2/transactions":{"get":{"tags":["Activities"],"summary":"Get point transactions with pagination","description":"Retrieve paginated list of point transactions/activities","parameters":[{"name":"shopifyCustomerId","in":"query","schema":{"type":"string"},"description":"Filter by Shopify customer ID.\n**Note:** At least one of `shopifyCustomerId` or `customerId` is required.\n"},{"name":"customerId","in":"query","schema":{"type":"string"},"description":"Filter by internal customer ID.\n**Note:** At least one of `shopifyCustomerId` or `customerId` is required.\n"},{"name":"before","in":"query","schema":{"type":"string"},"description":"Cursor for pagination (before) - Firestore document ID of activity to paginate before"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor for pagination (after) - Firestore document ID of activity to paginate after"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":1000},"description":"Number of transactions per page"},{"name":"type","in":"query","schema":{"type":"string","enum":["earn_point","redeem_point","adjust_point"]},"description":"Filter by activity type"},{"name":"event","in":"query","schema":{"type":"string"},"description":"Filter by specific event"},{"name":"source","in":"query","schema":{"type":"string","enum":["admin","user","rest_api","webhook"]},"description":"Filter by activity source"},{"name":"created_at_min","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter activities created after this date"},{"name":"created_at_max","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter activities created before this date"},{"name":"order","in":"query","schema":{"type":"string","enum":["createdAt_desc","createdAt_asc"],"default":"createdAt_desc"},"description":"Sort order for results"},{"name":"hasCount","in":"query","schema":{"type":"boolean","default":false},"description":"Include total count in response (may increase response time)"}],"responses":{"200":{"description":"Paginated list of transactions","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Activity"}}}}]}}}}}}}}}
```

## Get transaction by ID

> Retrieve details of a specific point transaction

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Activities","description":"Point activities and transactions"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Activity":{"type":"object","description":"Point transaction/activity with all fields that may be returned by the API. Note: Actual responses may only include non-null fields due to automatic filtering.","properties":{"id":{"type":"string","description":"Activity ID"},"shopId":{"type":"string","description":"Shop ID"},"customerId":{"type":"string","description":"Internal customer ID"},"shopifyCustomerId":{"type":"integer","description":"Shopify customer ID"},"email":{"type":"string","format":"email","description":"Customer email address"},"content":{"type":"string","description":"Activity description/content"},"type":{"type":"string","description":"Activity type"},"source":{"type":"string","description":"Source of the activity"},"event":{"type":"string","description":"Program event that triggered this activity"},"oldPoint":{"type":"integer","description":"Previous point balance"},"newPoint":{"type":"integer","description":"New point balance after this activity"},"programId":{"type":"string","nullable":true,"description":"Associated program ID"},"programTitle":{"type":"string","nullable":true,"description":"Associated program title"},"priceRuleId":{"type":"string","nullable":true,"description":"Shopify price rule ID for discounts"},"discountId":{"type":"string","nullable":true,"description":"Shopify discount ID"},"couponCode":{"type":"string","nullable":true,"description":"Generated coupon code"},"orderId":{"type":"string","nullable":true,"description":"Associated Shopify order ID"},"orderName":{"type":"string","nullable":true,"description":"Shopify order name"},"orderNumber":{"type":"integer","nullable":true,"description":"Shopify order number"},"orderCurrency":{"type":"string","nullable":true,"description":"Order currency code"},"earnBy":{"type":"string","nullable":true,"description":"How points were earned (price/order)"},"rateMoney":{"type":"number","nullable":true,"description":"Money to points conversion rate"},"earnPoint":{"type":"integer","nullable":true,"description":"Points earned in this activity"},"spendPoint":{"type":"integer","nullable":true,"description":"Points spent in this activity"},"referralCustomerEmail":{"type":"string","nullable":true,"description":"Email of referring customer"},"referredCustomerEmail":{"type":"string","nullable":true,"description":"Email of referred customer"},"milestoneOrder":{"type":"integer","nullable":true,"description":"Milestone order number"},"isPendingPointPlaceOrder":{"type":"boolean","nullable":true,"description":"Whether points are pending for order"},"refundPendingPoint":{"type":"integer","nullable":true,"description":"Refunded pending points"},"pendingPointUntil":{"type":"string","format":"date-time","nullable":true,"description":"When pending points expire"},"adminNote":{"type":"string","nullable":true,"description":"Admin note for this activity"},"userNote":{"type":"string","nullable":true,"description":"User note for this activity"},"reason":{"type":"string","nullable":true,"description":"Reason for the activity"},"createdAt":{"type":"string","format":"date-time","description":"Activity creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/rest_api/v2/transactions/{transactionId}":{"get":{"tags":["Activities"],"summary":"Get transaction by ID","description":"Retrieve details of a specific point transaction","parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string"},"description":"Transaction ID"}],"responses":{"200":{"description":"Transaction details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Activity"}}}]}}}}}}}}}
```

## Award points to customer

> Add points to a customer's account

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Activities","description":"Point activities and transactions"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/transactions/points/award":{"post":{"tags":["Activities"],"summary":"Award points to customer","description":"Add points to a customer's account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shopifyCustomerId":{"type":"string","description":"Shopify customer ID"},"point":{"type":"integer","description":"Points to award"},"adminNote":{"type":"string","description":"Internal note for admin reference"},"userNote":{"type":"string","description":"Note visible to customer"},"reason":{"type":"string","description":"Reason for awarding points"}},"required":["shopifyCustomerId","point"]}}}},"responses":{"200":{"description":"Points awarded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}}}}}}}
```

## Deduct points from customer

> Remove points from a customer's account

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Activities","description":"Point activities and transactions"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/transactions/points/deduct":{"post":{"tags":["Activities"],"summary":"Deduct points from customer","description":"Remove points from a customer's account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shopifyCustomerId":{"type":"string","description":"Shopify customer ID"},"point":{"type":"integer","description":"Points to deduct"},"adminNote":{"type":"string","description":"Internal note for admin reference"},"userNote":{"type":"string","description":"Note visible to customer"},"reason":{"type":"string","description":"Reason for deducting points"}},"required":["shopifyCustomerId","point"]}}}},"responses":{"200":{"description":"Points deducted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}}}}}}}
```

## Adjust customer points

> Adjust customer points (positive or negative adjustment)

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Activities","description":"Point activities and transactions"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/transactions/points/adjust":{"post":{"tags":["Activities"],"summary":"Adjust customer points","description":"Adjust customer points (positive or negative adjustment)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shopifyCustomerId":{"type":"string","description":"Shopify customer ID"},"point":{"type":"integer","description":"Points adjustment (positive or negative)"},"adminNote":{"type":"string","description":"Internal note for admin reference"},"userNote":{"type":"string","description":"Note visible to customer"},"reason":{"type":"string","description":"Reason for adjusting points"}},"required":["shopifyCustomerId","point"]}}}},"responses":{"200":{"description":"Points adjusted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}}}}}}}
```

## Reset customer points

> Set customer points to a specific value

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Activities","description":"Point activities and transactions"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/transactions/points/reset":{"post":{"tags":["Activities"],"summary":"Reset customer points","description":"Set customer points to a specific value","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shopifyCustomerId":{"type":"string","description":"Shopify customer ID"},"point":{"type":"integer","description":"New points balance to set"},"adminNote":{"type":"string","description":"Internal note for admin reference"},"userNote":{"type":"string","description":"Note visible to customer"},"reason":{"type":"string","description":"Reason for resetting points"}},"required":["shopifyCustomerId","point"]}}}},"responses":{"200":{"description":"Points reset successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}}}}}}}
```