User guide

Activities

Point activities and transactions

Get point transactions with pagination

get

Retrieve paginated list of point transactions/activities

Query parameters
shopifyCustomerIdstringOptional

Filter by Shopify customer ID. Note: At least one of shopifyCustomerId or customerId is required.

customerIdstringOptional

Filter by internal customer ID. Note: At least one of shopifyCustomerId or customerId is required.

beforestringOptional

Cursor for pagination (before) - Firestore document ID of activity to paginate before

afterstringOptional

Cursor for pagination (after) - Firestore document ID of activity to paginate after

limitinteger · min: 1 · max: 1000Optional

Number of transactions per page

Default: 10
typestring · enumOptional

Filter by activity type

Possible values:
eventstringOptional

Filter by specific event

sourcestring · enumOptional

Filter by activity source

Possible values:
created_at_minstring · date-timeOptional

Filter activities created after this date

created_at_maxstring · date-timeOptional

Filter activities created before this date

orderstring · enumOptional

Sort order for results

Default: createdAt_descPossible values:
hasCountbooleanOptional

Include total count in response (may increase response time)

Default: false
Responses
200

Paginated list of transactions

application/json
Responseall of
get
GET /rest_api/v2/transactions HTTP/1.1
Host: dev-api.joy.so
Accept: */*
200

Paginated list of transactions

{
  "success": true,
  "data": [
    {
      "id": "activity_123",
      "customerId": "cust_abc",
      "shopifyCustomerId": "7891234567890",
      "type": "earn_point",
      "event": "sign_up",
      "oldPoint": 0,
      "newPoint": 100,
      "earnPoint": 100,
      "source": "rest_api",
      "createdAt": "2025-08-12T08:30:00.000Z"
    },
    {
      "id": "activity_124",
      "customerId": "cust_abc",
      "shopifyCustomerId": "7891234567890",
      "type": "redeem_point",
      "event": "amount_discount",
      "oldPoint": 100,
      "newPoint": 50,
      "spendPoint": 50,
      "source": "user",
      "createdAt": "2025-08-12T07:15:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "hasNext": true,
      "hasPre": false,
      "total": 45,
      "totalPage": 3
    }
  },
  "timestamp": "2025-08-12T08:30:00.000Z"
}

Get transaction by ID

get

Retrieve details of a specific point transaction

Path parameters
transactionIdstringRequired

Transaction ID

Responses
200

Transaction details

application/json
Responseall of
get
GET /rest_api/v2/transactions/{transactionId} HTTP/1.1
Host: dev-api.joy.so
Accept: */*
200

Transaction details

{
  "success": true,
  "data": {
    "id": "act_abc123",
    "shopId": "shop_xyz789",
    "customerId": "cust_def456",
    "shopifyCustomerId": 7801029525739,
    "email": "[email protected]",
    "content": "Award points via REST API",
    "type": "earnPoint",
    "source": "rest_api",
    "event": "earn_point_rest_api",
    "oldPoint": 50,
    "newPoint": 150,
    "programId": "prog_abc123",
    "programTitle": "Manual Point Award",
    "priceRuleId": null,
    "discountId": null,
    "couponCode": null,
    "orderId": null,
    "orderName": null,
    "orderNumber": null,
    "orderCurrency": null,
    "earnBy": null,
    "rateMoney": null,
    "earnPoint": 100,
    "spendPoint": null,
    "referralCustomerEmail": null,
    "referredCustomerEmail": null,
    "milestoneOrder": null,
    "isPendingPointPlaceOrder": null,
    "refundPendingPoint": null,
    "pendingPointUntil": null,
    "adminNote": null,
    "userNote": null,
    "reason": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Award points to customer

post

Add points to a customer's account

Header parameters
X-Joy-Loyalty-App-KeystringRequired

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringRequired

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}
Body
shopifyCustomerIdstringRequired

Shopify customer ID

Example: 8720295559390
pointintegerRequired

Points to award

Example: 100
adminNotestringOptional

Internal note for admin reference

Example: Bonus points for customer loyalty
userNotestringOptional

Note visible to customer

Example: Loyalty bonus - thank you for being a valued customer!
reasonstringOptional

Reason for awarding points

Example: manual_adjustment
Responses
200

Points awarded successfully

application/json
post
POST /rest_api/v2/transactions/points/award HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 194

{
  "shopifyCustomerId": "8720295559390",
  "point": 100,
  "adminNote": "Bonus points for customer loyalty",
  "userNote": "Loyalty bonus - thank you for being a valued customer!",
  "reason": "manual_adjustment"
}
200

Points awarded successfully

{
  "success": true,
  "data": {},
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Deduct points from customer

post

Remove points from a customer's account

Header parameters
X-Joy-Loyalty-App-KeystringRequired

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringRequired

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}
Body
shopifyCustomerIdstringRequired

Shopify customer ID

Example: 8720295559390
pointintegerRequired

Points to deduct

Example: 50
adminNotestringOptional

Internal note for admin reference

Example: Points deduction for policy violation
userNotestringOptional

Note visible to customer

Example: Points adjusted due to return policy
reasonstringOptional

Reason for deducting points

Example: policy_adjustment
Responses
200

Points deducted successfully

application/json
post
POST /rest_api/v2/transactions/points/deduct HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "shopifyCustomerId": "8720295559390",
  "point": 50,
  "adminNote": "Points deduction for policy violation",
  "userNote": "Points adjusted due to return policy",
  "reason": "policy_adjustment"
}
200

Points deducted successfully

{
  "success": true,
  "data": {},
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Adjust customer points

post

Adjust customer points (positive or negative adjustment)

Body
shopifyCustomerIdstringRequired

Shopify customer ID

Example: 8720295559390
pointintegerRequired

Points adjustment (positive or negative)

Example: -25
adminNotestringOptional

Internal note for admin reference

Example: Correcting points balance discrepancy
userNotestringOptional

Note visible to customer

Example: Points balance correction
reasonstringOptional

Reason for adjusting points

Example: balance_correction
Responses
200

Points adjusted successfully

application/json
post
POST /rest_api/v2/transactions/points/adjust HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 170

{
  "shopifyCustomerId": "8720295559390",
  "point": -25,
  "adminNote": "Correcting points balance discrepancy",
  "userNote": "Points balance correction",
  "reason": "balance_correction"
}
200

Points adjusted successfully

{
  "success": true,
  "data": {},
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Reset customer points

post

Set customer points to a specific value

Body
shopifyCustomerIdstringRequired

Shopify customer ID

Example: 8720295559390
pointintegerRequired

New points balance to set

Example: 0
adminNotestringOptional

Internal note for admin reference

Example: Resetting points balance for new program
userNotestringOptional

Note visible to customer

Example: Points reset for new loyalty program launch
reasonstringOptional

Reason for resetting points

Example: program_migration
Responses
200

Points reset successfully

application/json
post
POST /rest_api/v2/transactions/points/reset HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "shopifyCustomerId": "8720295559390",
  "point": 0,
  "adminNote": "Resetting points balance for new program",
  "userNote": "Points reset for new loyalty program launch",
  "reason": "program_migration"
}
200

Points reset successfully

{
  "success": true,
  "data": {},
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}
PreviousCustomersNextRewards