REST API v2
API references
Activities

Activities

Point activities and transactions

Get point transactions with pagination

GET/rest_api/v2/transactions

Retrieve paginated list of point transactions/activities

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
shopifyCustomerIdquery · stringOptional

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

customerIdquery · stringOptional

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

beforequery · stringOptional

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

afterquery · stringOptional

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

limitquery · integerOptional

Number of transactions per page

typequery · stringOptional

Filter by activity type

eventquery · stringOptional

Filter by specific event

sourcequery · stringOptional

Filter by activity source

created_at_minquery · string · date-timeOptional

Filter activities created after this date

created_at_maxquery · string · date-timeOptional

Filter activities created before this date

orderquery · stringOptional

Sort order for results

hasCountquery · booleanOptional

Include total count in response (may increase response time)

Responses
200Paginated list of transactions
successbooleanOptional
Example: true
dataActivity[]Required
Show properties
idstringOptional

Activity ID

Example: "act_abc123"
shopIdstringOptional

Shop ID

Example: "shop_xyz789"
customerIdstringOptional

Internal customer ID

Example: "cust_def456"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7801029525739
emailstring · emailOptional

Customer email address

Example: "[email protected]"
contentstringOptional

Activity description/content

Example: "Award points via REST API"
typestringOptional

Activity type

Example: "earnPoint"
sourcestringOptional

Source of the activity

Example: "rest_api"
eventstringOptional

Program event that triggered this activity

Example: "earn_point_rest_api"
oldPointintegerOptional

Previous point balance

Example: 50
newPointintegerOptional

New point balance after this activity

Example: 150
programIdstringOptional

Associated program ID

Example: "prog_abc123"
programTitlestringOptional

Associated program title

Example: "Manual Point Award"
priceRuleIdstringOptional

Shopify price rule ID for discounts

Example: null
discountIdstringOptional

Shopify discount ID

Example: null
couponCodestringOptional

Generated coupon code

Example: null
orderIdstringOptional

Associated Shopify order ID

Example: null
orderNamestringOptional

Shopify order name

Example: null
orderNumberintegerOptional

Shopify order number

Example: null
orderCurrencystringOptional

Order currency code

Example: null
earnBystringOptional

How points were earned (price/order)

Example: null
rateMoneynumberOptional

Money to points conversion rate

Example: null
earnPointintegerOptional

Points earned in this activity

Example: 100
spendPointintegerOptional

Points spent in this activity

Example: null
referralCustomerEmailstringOptional

Email of referring customer

Example: null
referredCustomerEmailstringOptional

Email of referred customer

Example: null
milestoneOrderintegerOptional

Milestone order number

Example: null
isPendingPointPlaceOrderbooleanOptional

Whether points are pending for order

Example: null
refundPendingPointintegerOptional

Refunded pending points

Example: null
pendingPointUntilstring · date-timeOptional

When pending points expire

Example: null
adminNotestringOptional

Admin note for this activity

Example: null
userNotestringOptional

User note for this activity

Example: null
reasonstringOptional

Reason for the activity

Example: null
createdAtstring · date-timeOptional

Activity creation timestamp

Example: "2024-01-15T10:30:00.000Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2024-01-15T10:30:00.000Z"
metaobjectOptional

Pagination metadata container

Show properties
paginationobjectOptional
Show properties
hasNextbooleanRequired

True if more results exist after current page

hasPrebooleanRequired

True if results exist before current page

totalintegerOptional

Total count of all matching results (when available)

totalPageintegerOptional

Total number of pages calculated as ceil(total/limit) (when available)

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/transactions
GET /rest_api/v2/transactions HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Paginated 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/rest_api/v2/transactions/{transactionId}

Retrieve details of a specific point transaction

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
transactionIdpath · stringRequired

Transaction ID

Responses
200Transaction details
successbooleanOptional
Example: true
dataActivityOptional

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.

Show properties
idstringOptional

Activity ID

Example: "act_abc123"
shopIdstringOptional

Shop ID

Example: "shop_xyz789"
customerIdstringOptional

Internal customer ID

Example: "cust_def456"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7801029525739
emailstring · emailOptional

Customer email address

Example: "[email protected]"
contentstringOptional

Activity description/content

Example: "Award points via REST API"
typestringOptional

Activity type

Example: "earnPoint"
sourcestringOptional

Source of the activity

Example: "rest_api"
eventstringOptional

Program event that triggered this activity

Example: "earn_point_rest_api"
oldPointintegerOptional

Previous point balance

Example: 50
newPointintegerOptional

New point balance after this activity

Example: 150
programIdstringOptional

Associated program ID

Example: "prog_abc123"
programTitlestringOptional

Associated program title

Example: "Manual Point Award"
priceRuleIdstringOptional

Shopify price rule ID for discounts

Example: null
discountIdstringOptional

Shopify discount ID

Example: null
couponCodestringOptional

Generated coupon code

Example: null
orderIdstringOptional

Associated Shopify order ID

Example: null
orderNamestringOptional

Shopify order name

Example: null
orderNumberintegerOptional

Shopify order number

Example: null
orderCurrencystringOptional

Order currency code

Example: null
earnBystringOptional

How points were earned (price/order)

Example: null
rateMoneynumberOptional

Money to points conversion rate

Example: null
earnPointintegerOptional

Points earned in this activity

Example: 100
spendPointintegerOptional

Points spent in this activity

Example: null
referralCustomerEmailstringOptional

Email of referring customer

Example: null
referredCustomerEmailstringOptional

Email of referred customer

Example: null
milestoneOrderintegerOptional

Milestone order number

Example: null
isPendingPointPlaceOrderbooleanOptional

Whether points are pending for order

Example: null
refundPendingPointintegerOptional

Refunded pending points

Example: null
pendingPointUntilstring · date-timeOptional

When pending points expire

Example: null
adminNotestringOptional

Admin note for this activity

Example: null
userNotestringOptional

User note for this activity

Example: null
reasonstringOptional

Reason for the activity

Example: null
createdAtstring · date-timeOptional

Activity creation timestamp

Example: "2024-01-15T10:30:00.000Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2024-01-15T10:30:00.000Z"
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/transactions/{transactionId}
GET /rest_api/v2/transactions/{transactionId} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Transaction 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/rest_api/v2/transactions/points/award

Add points to a customer's account

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Request 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
200Points awarded successfully
successbooleanOptional
Example: true
dataobjectOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
POST/rest_api/v2/transactions/points/award
POST /rest_api/v2/transactions/points/award HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 215


{
  "shopifyCustomerId": "8720295559390",
  "point": 100,
  "adminNote": "Bonus points for customer loyalty",
  "userNote": "Loyalty bonus - thank you for being a valued customer!",
  "reason": "manual_adjustment"
}
200Points awarded successfully
{
  "success": true,
  "data": {},
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Deduct points from customer

POST/rest_api/v2/transactions/points/deduct

Remove points from a customer's account

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Request 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
200Points deducted successfully
successbooleanOptional
Example: true
dataobjectOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
POST/rest_api/v2/transactions/points/deduct
POST /rest_api/v2/transactions/points/deduct HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 200


{
  "shopifyCustomerId": "8720295559390",
  "point": 50,
  "adminNote": "Points deduction for policy violation",
  "userNote": "Points adjusted due to return policy",
  "reason": "policy_adjustment"
}
200Points deducted successfully
{
  "success": true,
  "data": {},
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Adjust customer points

POST/rest_api/v2/transactions/points/adjust

Adjust customer points (positive or negative adjustment)

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Request 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
200Points adjusted successfully
successbooleanOptional
Example: true
dataobjectOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
POST/rest_api/v2/transactions/points/adjust
POST /rest_api/v2/transactions/points/adjust HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 191


{
  "shopifyCustomerId": "8720295559390",
  "point": -25,
  "adminNote": "Correcting points balance discrepancy",
  "userNote": "Points balance correction",
  "reason": "balance_correction"
}
200Points adjusted successfully
{
  "success": true,
  "data": {},
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Reset customer points

POST/rest_api/v2/transactions/points/reset

Set customer points to a specific value

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Request 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
200Points reset successfully
successbooleanOptional
Example: true
dataobjectOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
POST/rest_api/v2/transactions/points/reset
POST /rest_api/v2/transactions/points/reset HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 209


{
  "shopifyCustomerId": "8720295559390",
  "point": 0,
  "adminNote": "Resetting points balance for new program",
  "userNote": "Points reset for new loyalty program launch",
  "reason": "program_migration"
}
200Points reset successfully
{
  "success": true,
  "data": {},
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}
CustomersRewards
Product
Install AppWebsiteBook a Demo
Developers
JavaScript SDKREST API v2Webhook API
Company
Avada GroupHelp CenterContact
© 2026 Joy Loyalty by Avada Group. All rights reserved.