Programs

Earning and spending programs management

Get earning programs

GET/rest_api/v2/programs/earning

Retrieve all earning programs for the authenticated shop

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Responses

200List of earning programs

successbooleanOptional

Example: true

dataProgram[]Optional

Show properties

idstringOptional

Example: "prog_abc123"

titlestringOptional

Example: "Sign Up Bonus"

typestringOptional

Example: "earning"

eventstringOptional

Example: "sign_up"

statusbooleanOptional

Example: true

priorityintegerOptional

Example: 1

createdAtstring · date-timeOptional

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

updatedAtstring · date-timeOptional

Example: "2024-01-20T14:45:30.000Z"

expiredbooleanOptional

Example: false

isDraftbooleanOptional

Example: false

earnBystringOptional

Example: "price"

rateMoneynumberOptional

Example: 1

earnPointintegerOptional

Example: 100

startDatestring · date-timeOptional

Example: "2024-01-01T00:00:00.000Z"

endDatestring · date-timeOptional

Example: "2024-12-31T23:59:59.000Z"

autoRemovePointsbooleanOptional

Example: false

appliedPlaceOrderTostringOptional

Example: "all"

appliedSourcestring[]Optional

Example: ["web","pos"]

translateTitleobjectOptional

Example: {}

typeMilestonestringOptional

Example: null

milestonesobject[]Optional

Example: []

spendPointintegerOptional

Example: 500

earnAmountnumberOptional

Example: 10

redeemTypestringOptional

Example: "amount_discount"

appliedTostringOptional

Example: "all"

appliedCollectionIdsstring[]Optional

Example: []

redeemInstringOptional

Example: "available_in_online_store"

orderReqstringOptional

Example: "none"

orderReqAmountnumberOptional

Example: 0

minSpendPointstringOptional

Example: ""

maxSpendPointstringOptional

Example: ""

expiredTimestringOptional

Example: ""

userAvailabilitystringOptional

Example: "userRedeemed"

showLoyaltyPagebooleanOptional

Example: true

limitRedeemstringOptional

Example: "redeemWithoutLimit"

totalLimitationRedeemintegerOptional

Example: 0

combinedWithstring[]Optional

Example: []

specificProductsobject[]Optional

Example: []

specificProductIdsstring[]Optional

Example: []

specificCollectionsobject[]Optional

Example: []

variantIdsstring[]Optional

Example: []

freeProductIdsstring[]Optional

Example: []

giftStatusstringOptional

Example: "none"

excludeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

includeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

conditionsobject[]Optional

earnPointsTiersobject[]Optional

Show properties

earnPointintegerOptional

rateMoneynumberOptional

roundingMethodstringOptional

Example: "round"

skipEarnPointGuestbooleanOptional

Example: false

metaobjectOptional

Show properties

countintegerOptional

Number of items returned

messagestringOptional

Example: "Operation completed successfully"

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

403Plan upgrade required

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

500Internal server error

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

GET/rest_api/v2/programs/earning

GET /rest_api/v2/programs/earning 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: */*

200List of earning programs

{
  "success": true,
  "data": [
    {
      "id": "prog_earning_001",
      "title": "Sign Up Bonus",
      "description": "Get points for creating an account",
      "type": "earning",
      "event": "sign_up",
      "status": true,
      "earnPoint": 100,
      "rateMoney": 1,
      "priority": 1,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:30.000Z"
    },
    {
      "id": "prog_earning_002",
      "title": "Place Order Reward",
      "description": "Earn points for every purchase",
      "type": "earning",
      "event": "place_order",
      "status": true,
      "earnBy": "price",
      "earnPoint": 1,
      "rateMoney": 1,
      "appliedPlaceOrderTo": "all",
      "appliedSource": [
        "web",
        "pos"
      ],
      "autoRemovePoints": false,
      "skipEarnPointGuest": false,
      "roundingMethod": "round",
      "createdAt": "2024-01-10T08:15:00.000Z",
      "updatedAt": "2024-01-25T16:20:45.000Z"
    }
  ]
}

Create earning program

POST/rest_api/v2/programs/earning

Create a new earning program. The event field determines the program type and which fields are required/validated.

Common required fields (all events): title, event Common optional fields: status (default varies by event), priority, isDraft, description, startDate, endDate

Event Groups & Required Fields

Simple one-time rewards:

Event	Required	Optional
`sign_up`	`earnPoint`	`typeEarn` (point / percentage / amount). Percentage: earnPoint <= 100. Discount fields (prefix, appliedTo, expiredAfter, combinedWith) only when typeEarn != "point"
`sign_up_newsletter`	`earnPoint`	`autoSyncExistingNewsletter`, `earnWidgetPopup`, `excludedSubscribedBefore`. Points only (typeEarn forced to "point")
`birthday`	`earnPoint` (unless multi-reward)	`typeEarn` (point / percentage / amount / bxgy / free_gift), `dateFormat` (MM/DD, DD/MM, MM/DD/YYYY, DD/MM/YYYY, YYYY/MM/DD), `typeDeliveryMethod` (automatic / manual), `typeRewardTiming` (exact_birthday / begin_of_month / around_birthday). around_birthday requires manual delivery
`member_anniversary`	`earnPoint`, `duration`	`duration` pattern: "N unit" e.g. "1 Y", "6 M", "30 D". Units: Y, M, D, W, min

Social engagement (all require earnPoint):

Event	Required	Optional
`like_facebook`, `follow_instagram`, `follow_twitter`, `follow_pinterest`, `follow_tiktok`, `subscribe_youtube`, `join_discord`, `join_telegram`	`urlAccount`	—
`share_facebook`, `share_twitter`	`urlAccount`	`enabledAntiCheat`, `message`
`join_whatsapp`, `join_line`	`typeJoin` (link / qr_code)	When link: `urlAccount`. When qr_code + whatsapp: `imageQRCode`
`comment_instagram`	—	`postType` (all_posts / specific_posts), keyword filters, auto-reply, DM
`story_mention_instagram`	—	DM notification support

Do NOT send social or action fields — they are auto-derived from event.

Purchase-based:

Event	Required	Optional
`place_order`, `place_order_subscription`	`earnPoint`	`earnBy` (price / fixed_order / quantity / order). price: requires `rateMoney`. quantity: requires `rateItem`. `roundingMethod` (roundingNearest / roundingUp / roundingDown), `autoRemovePoints`, `skipEarnPointGuest`, rule engine: `statusUseCondition`, `conditions`, `typeCondition`

typeEarn limited to "point" or "store_credit" for purchase events.

Content & action (all require earnPoint unless noted):

Event	Required	Optional
`write_review`	`reviewApp` (airReviewApp, judgeMeApp, yotpoApp, feraApp, etc.)	Shopify Flow apps also require `descriptionReview`
`fill_survey`	—	`link` (survey URL, no https:// prefix). earnPoint informational only
`submit_form`	—	`autoApprove`, `instantRewardEnabled`, `instantRewardPoints`, `requireImage`
`submit_receipt`	—	Admin approval required. Supports point/percentage/amount
`google_maps_review`	`urlLocation`	`isInstantPoint`, `instantPoint` (must be < earnPoint)
`interact_website`	—	Uses `limitUnit` / `limitInterval` always. Earns once per period
`streak_interact_website`	`description`, `startDate`, `endDate`, `streakMilestones`	streakMilestones: array with day (3/5/7) and earnPoint
`custom_program`	`typeCustom` (visit_page_{id} / completed_profile_{id} / shopify_flow_trigger_{id} / custom_trigger_{id})	visit_page: `linkVisit`. completed_profile: `fieldProfile` (name/email/phone)
`milestone`	`typeMilestone`, `milestones` (array, min 1)	typeMilestone values: milestone_order, milestone_amount_spent, milestone_earned_point, milestone_reviews, milestone_inactivity, milestone_referral, milestone_subscription

Date Range (shared)

startDate — optional. If omitted, defaults to current time (program active immediately). Required for streak_interact_website.
endDate — optional. If omitted, program never expires. Required for streak_interact_website.
Note: spending programs also default startDate to current time if omitted. They use expiredAfter/expiredTime for coupon expiration after redemption.

Earning Frequency (shared across most events)

hasLimit (default varies by event) — enable earning frequency cap
limitUnit (minute|hour|day|week|month|year|lifetime, default: "lifetime")
limitInterval — required when hasLimit=true AND limitUnit != "lifetime"

VIP Tier Overrides (shared)

isAppliedVipTier (default: false) — enable tier-specific earn rates
earnPointsTiers (object) — tier ID → earnPoint mapping

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Request body

titlestringRequired

Program display title

eventstringRequired

Event type — determines required fields. See endpoint description for details per event.

statusbooleanOptional

Whether the program is active. Default varies by event (true for sign_up/place_order, false for social/content events).

earnPointnumberOptional

Points to award. Required for most events. For percentage typeEarn, must be <= 100.

typeEarnstringOptional

Reward type. 'point' awards loyalty points. 'percentage'/'amount' create discount coupons. sign_up, member_anniversary, submit_receipt support point/percentage/amount. birthday supports all five types: point, percentage, amount, bxgy, free_gift. place_order only supports point/store_credit.

earnBystringOptional

How points are calculated for place_order events. price: spend $rateMoney earn $earnPoint points. fixed_order: flat points per order (requires rateMoney). quantity: points per item (requires rateItem). order: fixed earnPoint per order.

rateMoneynumberOptional

Currency-to-points ratio. Required when earnBy is 'price' or 'fixed_order'.

rateItemnumberOptional

Item-to-points ratio. Required when earnBy is 'quantity'.

urlAccountstringOptional

Social media profile/page URL. Required for simple social, share social events. Must start with http:// or https://.

urlLocationstringOptional

Google Maps location URL. Required for google_maps_review.

typeJoinstringOptional

Join method for join_whatsapp, join_line. 'link': urlAccount required. 'qr_code': imageQRCode required (whatsapp only).

imageQRCodestringOptional

QR code image URL. Required when typeJoin='qr_code' and event='join_whatsapp'.

reviewAppstringOptional

Review app integration. Required for write_review.

durationstringOptional

Anniversary interval pattern 'N unit' (e.g. '1 Y', '6 M', '30 D', '2 W'). Valid units: Y, M, D, W, min. Required for member_anniversary.

typeCustomstringOptional

Custom program type '{prefix}_{id}'. Prefixes: visit_page, completed_profile, shopify_flow_trigger, custom_trigger. Required for custom_program.

typeMilestonestringOptional

Milestone trigger type. Required for milestone event.

milestonesobject[]Optional

Milestone thresholds array (min 1). Required for milestone event. Each item: {value, unit? (for inactivity), rewards?, rewardLogic?}.

Show properties

valueintegerOptional

Threshold value

unitstringOptional

Time unit for milestone_inactivity only

rewardLogicstringOptional

rewardsobject[]Optional

streakMilestonesobject[]Optional

Streak bonus milestones. Required for streak_interact_website. Each: {day: 3|5|7, earnPoint: number}.

Show properties

dayintegerOptional

earnPointintegerOptional

roundingMethodstringOptional

Rounding for place_order point calculations.

autoRemovePointsbooleanOptional

Remove earned points on order refund. For place_order.

skipEarnPointGuestbooleanOptional

Skip earning for guest customers. For place_order.

appliedPlaceOrderTostringOptional

Who can earn from place_order.

hasLimitbooleanOptional

Enable earning frequency cap.

limitUnitstringOptional

Full enum shown. Some events restrict to subset: social events allow day-lifetime only, birthday allows year/lifetime only, place_order allows minute-lifetime.

limitIntervalintegerOptional

Number of limitUnit periods. Required when hasLimit=true AND limitUnit != 'lifetime'.

isAppliedVipTierbooleanOptional

Enable tier-specific earn rates. When true, use earnPointsTiers to override earnPoint per tier.

earnPointsTiersobjectOptional

Tier-specific earn rates. Keys are tier IDs, values are earnPoint overrides.

priorityintegerOptional

Program priority order. Lower numbers = higher priority.

isDraftbooleanOptional

Save as draft without activating.

startDatestring · date-timeOptional

Program activation date (ISO 8601). If omitted, defaults to current time (program active immediately). Required for streak_interact_website.

endDatestring · date-timeOptional

Program expiration date (ISO 8601). If omitted, program never expires. Required for streak_interact_website.

descriptionstringOptional

Program description shown to customers. Used by social, submit_form, streak_interact_website, and other events.

enabledAntiCheatbooleanOptional

Anti-cheat verification. Used by share social, comment_instagram, story_mention_instagram, write_review, place_order, custom_program.

prefixstringOptional

Discount code prefix. For discount typeEarn (percentage/amount).

appliedTostringOptional

Discount product scope. For discount typeEarn.

expiredAfterstringOptional

Discount coupon expiration. For discount typeEarn.

combinedWithstring[]Optional

Discount combination rules. For discount typeEarn.

appliedDiscountToSaleChannelstringOptional

Sale channel for discount coupons. For discount typeEarn (percentage/amount).

userAvailabilitystringOptional

Who can use the coupon. For discount typeEarn.

appliedCollectionIdsstring[]Optional

Collection IDs. Required when appliedTo='specific'. For discount typeEarn.

specificProductsobject[]Optional

Product objects (max 100). Required when appliedTo='sf_product'. For discount typeEarn.

specificProductIdsstring[]Optional

Product IDs (max 100). For discount typeEarn.

orderReqstringOptional

Order requirement for discount. For discount typeEarn.

orderReqAmountnumberOptional

Min order amount. Required when orderReq='min_amount'.

orderReqQuantitynumberOptional

Min order quantity. Required when orderReq='min_quantity'.

expiredTimestringOptional

Specific expiration datetime. Required when expiredAfter='specific'.

isUsePrefixDiscountCodebooleanOptional

Whether to use prefix for discount codes. For discount typeEarn.

dateFormatstringOptional

Birthday date format. For birthday event.

typeDeliveryMethodstringOptional

Reward delivery method. For birthday event. 'around_birthday' timing requires 'manual'.

typeRewardTimingstringOptional

When to deliver birthday reward. 'around_birthday' only available with typeDeliveryMethod='manual'.

isUseLayoutMultiRewardsbooleanOptional

Enable multi-reward layout (customer picks between point/discount/free_gift). For birthday.

messagestringOptional

Share message text. For share_facebook, share_twitter.

postTypestringOptional

Target posts. For comment_instagram. When 'specific_posts': specificPostIds required.

specificPostIdsstring[]Optional

Instagram post IDs. Required when postType='specific_posts'.

enableIncludeKeywordsbooleanOptional

Enable keyword inclusion filter. For comment_instagram.

includeKeywordsstring[]Optional

Required keywords. Required when enableIncludeKeywords=true.

enableExcludeKeywordsbooleanOptional

Enable keyword exclusion filter. For comment_instagram.

excludeKeywordsstring[]Optional

Blocked keywords. Required when enableExcludeKeywords=true.

enableAutoReplybooleanOptional

Auto-reply to Instagram comments. For comment_instagram.

autoReplyMessagestringOptional

Auto-reply message. Supports {points} placeholder. Required when enableAutoReply=true.

enableDMNotificationbooleanOptional

Send DM notification. For comment_instagram, story_mention_instagram.

dmMessagestringOptional

DM message text. Supports {points}, {store_url}. Required when enableDMNotification=true.

descriptionReviewstringOptional

Review description. Required for Shopify Flow review apps: stampedApp, looxApp, okendoApp, ReviewsIoApp, growaveApp, typdalApp.

isAppliedExtraPointsbooleanOptional

Award bonus points for media attachments. For write_review.

extraPointsnumberOptional

Bonus points for media. Required when isAppliedExtraPoints=true (except reviewRocketApp).

autoApprovebooleanOptional

Auto-approve form submissions. For submit_form. If false, admin reviews before points awarded.

instantRewardEnabledbooleanOptional

Award partial points immediately when autoApprove=false. For submit_form.

instantRewardPointsintegerOptional

Partial points to award immediately. Required when autoApprove=false AND instantRewardEnabled=true.

requireImagebooleanOptional

Require image upload. For submit_form.

isInstantPointbooleanOptional

Award partial points before admin approval. For google_maps_review.

instantPointnumberOptional

Partial points (must be < earnPoint). Required when isInstantPoint=true.

linkVisitstringOptional

Page URL to visit. Required when typeCustom starts with 'visit_page'.

fieldProfilestring[]Optional

Profile fields to complete. Required when typeCustom starts with 'completed_profile'.

autoSyncExistingNewsletterbooleanOptional

Retroactively award points to existing subscribers. For sign_up_newsletter.

statusUseConditionbooleanOptional

Enable rule engine conditions. For place_order.

conditionsobject[]Optional

Rule engine conditions array. For place_order when statusUseCondition=true.

excludeProductsobject[]Optional

Products to exclude from earning. For place_order.

includeProductsobject[]Optional

Products to include for earning. For place_order.

earnPointShippingFeebooleanOptional

Include shipping fee in points calculation. For place_order.

earnPointTaxbooleanOptional

Include tax in points calculation. For place_order.

excludeGiftCardbooleanOptional

Exclude gift card products. For place_order.

enabledMaxEarnPointbooleanOptional

Cap maximum points per order. For place_order.

maxEarnPointnumberOptional

Max points per order. Required when enabledMaxEarnPoint=true.

excludeFreeGiftbooleanOptional

Exclude free gift items from earning. For place_order.

excludeStoreCreditbooleanOptional

Exclude store credit items from earning. For place_order.

typeProductMatchstringOptional

Product condition matching mode. 'all' = all conditions must match, 'any' = any condition matches. For place_order with rule engine.

typeConditionstringOptional

Condition type for rule engine. For place_order.

typeDateRangestringOptional

Date range type. 'static_date': uses startDate/endDate. 'dynamic_date': uses valueDateRange. For place_order.

valueDateRangestringOptional

Dynamic date range filter. For place_order with typeDateRange='dynamic_date'.

priorityPlaceOrderstringOptional

Rule execution priority (lower = higher). For place_order V2 rule engine.

stopProcessingbooleanOptional

Stop evaluating lower-priority rules after this rule matches. For place_order V2.

excludeOrderTagsstring[]Optional

Order tags to exclude from earning. For place_order.

earnWidgetPopupbooleanOptional

Enable widget popup for newsletter sign-up. For sign_up_newsletter.

excludedSubscribedBeforebooleanOptional

Exclude customers who subscribed before program activation. For sign_up_newsletter.

linkstringOptional

Survey URL (without https:// prefix). For fill_survey.

extraPointsForImagesnumberOptional

Bonus points for image attachments. For write_review.

extraPointsForVideosnumberOptional

Bonus points for video attachments. For write_review.

extraPointsModestringOptional

How bonus points are calculated. 'per_attachment': multiply by count. 'fixed': flat bonus. For write_review.

enabledMinCharactersbooleanOptional

Require minimum review length. For write_review.

minCharactersintegerOptional

Minimum character count. Required when enabledMinCharacters=true.

enableMinStarRatingbooleanOptional

Require minimum star rating. For write_review.

minStarRatingintegerOptional

Minimum star rating (1-5). Required when enableMinStarRating=true.

Responses

201Program created successfully

successbooleanOptional

Example: true

dataProgramOptional

Loyalty program (earning or spending) 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

Example: "prog_abc123"

titlestringOptional

Example: "Sign Up Bonus"

typestringOptional

Example: "earning"

eventstringOptional

Example: "sign_up"

statusbooleanOptional

Example: true

priorityintegerOptional

Example: 1

createdAtstring · date-timeOptional

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

updatedAtstring · date-timeOptional

Example: "2024-01-20T14:45:30.000Z"

expiredbooleanOptional

Example: false

isDraftbooleanOptional

Example: false

earnBystringOptional

Example: "price"

rateMoneynumberOptional

Example: 1

earnPointintegerOptional

Example: 100

startDatestring · date-timeOptional

Example: "2024-01-01T00:00:00.000Z"

endDatestring · date-timeOptional

Example: "2024-12-31T23:59:59.000Z"

autoRemovePointsbooleanOptional

Example: false

appliedPlaceOrderTostringOptional

Example: "all"

appliedSourcestring[]Optional

Example: ["web","pos"]

translateTitleobjectOptional

Example: {}

typeMilestonestringOptional

Example: null

milestonesobject[]Optional

Example: []

spendPointintegerOptional

Example: 500

earnAmountnumberOptional

Example: 10

redeemTypestringOptional

Example: "amount_discount"

appliedTostringOptional

Example: "all"

appliedCollectionIdsstring[]Optional

Example: []

redeemInstringOptional

Example: "available_in_online_store"

orderReqstringOptional

Example: "none"

orderReqAmountnumberOptional

Example: 0

minSpendPointstringOptional

Example: ""

maxSpendPointstringOptional

Example: ""

expiredTimestringOptional

Example: ""

userAvailabilitystringOptional

Example: "userRedeemed"

showLoyaltyPagebooleanOptional

Example: true

limitRedeemstringOptional

Example: "redeemWithoutLimit"

totalLimitationRedeemintegerOptional

Example: 0

combinedWithstring[]Optional

Example: []

specificProductsobject[]Optional

Example: []

specificProductIdsstring[]Optional

Example: []

specificCollectionsobject[]Optional

Example: []

variantIdsstring[]Optional

Example: []

freeProductIdsstring[]Optional

Example: []

giftStatusstringOptional

Example: "none"

excludeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

includeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

conditionsobject[]Optional

earnPointsTiersobject[]Optional

Show properties

earnPointintegerOptional

rateMoneynumberOptional

roundingMethodstringOptional

Example: "round"

skipEarnPointGuestbooleanOptional

Example: false

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional

Example: "Operation completed successfully"

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

400Validation error — missing required fields, invalid values, or constraint violations

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

403Plan upgrade required

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

409Duplicate program. Single-instance events allow only one program per shop. **Single-instance events** (1 per shop): sign_up, sign_up_newsletter, birthday, like_facebook, share_facebook, follow_instagram, follow_twitter, share_twitter, follow_pinterest, follow_tiktok, subscribe_youtube, join_discord, join_telegram, join_whatsapp, interact_website, streak_interact_website **Multi-instance events** (no limit): place_order, milestone, custom_program, submit_form, write_review, fill_survey, submit_receipt, member_anniversary, google_maps_review, comment_instagram, story_mention_instagram, join_line

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

POST/rest_api/v2/programs/earning

POST /rest_api/v2/programs/earning 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: 90

{
  "title": "Sign Up Bonus",
  "event": "sign_up",
  "earnPoint": 100,
  "status": true
}

201Program created successfully

{
  "success": true,
  "data": {
    "id": "pR7mKxQ2wT4vN9yB3jL6",
    "title": "Follow us on Instagram",
    "type": "earning",
    "event": "follow_instagram",
    "status": true,
    "earnPoint": 50,
    "social": "instagram",
    "action": "follow",
    "urlAccount": "https://instagram.com/yourshop",
    "hasLimit": true,
    "limitUnit": "lifetime",
    "isAppliedVipTier": false,
    "priority": 0,
    "isDraft": false,
    "createdAt": "2026-03-24T10:30:00.000Z",
    "updatedAt": "2026-03-24T10:30:00.000Z"
  },
  "meta": {},
  "timestamp": "2026-03-24T10:30:00.123Z"
}

Get programs by customer eligibility

GET/rest_api/v2/programs/earning/eligibility

Retrieve earning programs for a specific customer. Single earn event programs (like social media follows, sign up, birthday) will include an isEarned field indicating whether the customer has already earned points from that program.

Customer Identifier Required: Must provide either customerId or shopifyCustomerId parameter.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Parameters

shopifyCustomerIdquery · stringOptional

Shopify customer ID

customerIdquery · stringOptional

Internal customer ID

Responses

200Programs for customer with earned status

successbooleanOptional

Example: true

dataobject[]Optional

Show properties

idstringOptional

Example: "prog_abc123"

titlestringOptional

Example: "Sign Up Bonus"

typestringOptional

Example: "earning"

eventstringOptional

Example: "sign_up"

statusbooleanOptional

Example: true

priorityintegerOptional

Example: 1

createdAtstring · date-timeOptional

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

updatedAtstring · date-timeOptional

Example: "2024-01-20T14:45:30.000Z"

expiredbooleanOptional

Example: false

isDraftbooleanOptional

Example: false

earnBystringOptional

Example: "price"

rateMoneynumberOptional

Example: 1

earnPointintegerOptional

Example: 100

startDatestring · date-timeOptional

Example: "2024-01-01T00:00:00.000Z"

endDatestring · date-timeOptional

Example: "2024-12-31T23:59:59.000Z"

autoRemovePointsbooleanOptional

Example: false

appliedPlaceOrderTostringOptional

Example: "all"

appliedSourcestring[]Optional

Example: ["web","pos"]

translateTitleobjectOptional

Example: {}

typeMilestonestringOptional

Example: null

milestonesobject[]Optional

Example: []

spendPointintegerOptional

Example: 500

earnAmountnumberOptional

Example: 10

redeemTypestringOptional

Example: "amount_discount"

appliedTostringOptional

Example: "all"

appliedCollectionIdsstring[]Optional

Example: []

redeemInstringOptional

Example: "available_in_online_store"

orderReqstringOptional

Example: "none"

orderReqAmountnumberOptional

Example: 0

minSpendPointstringOptional

Example: ""

maxSpendPointstringOptional

Example: ""

expiredTimestringOptional

Example: ""

userAvailabilitystringOptional

Example: "userRedeemed"

showLoyaltyPagebooleanOptional

Example: true

limitRedeemstringOptional

Example: "redeemWithoutLimit"

totalLimitationRedeemintegerOptional

Example: 0

combinedWithstring[]Optional

Example: []

specificProductsobject[]Optional

Example: []

specificProductIdsstring[]Optional

Example: []

specificCollectionsobject[]Optional

Example: []

variantIdsstring[]Optional

Example: []

freeProductIdsstring[]Optional

Example: []

giftStatusstringOptional

Example: "none"

excludeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

includeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

conditionsobject[]Optional

earnPointsTiersobject[]Optional

Show properties

earnPointintegerOptional

rateMoneynumberOptional

roundingMethodstringOptional

Example: "round"

skipEarnPointGuestbooleanOptional

Example: false

isEarnedbooleanOptional

Only present for single earn event programs (social media follows, sign up, birthday, etc.). Indicates if customer has earned from this program.

metaobjectOptional

Show properties

countintegerOptional

Number of items returned

messagestringOptional

Example: "Operation completed successfully"

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

404Customer not found

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

GET/rest_api/v2/programs/earning/eligibility

GET /rest_api/v2/programs/earning/eligibility 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: */*

200Programs for customer with earned status

{
  "success": true,
  "data": [
    {
      "id": "prog_earning_001",
      "title": "Sign Up Bonus",
      "type": "earning",
      "event": "sign_up",
      "earnPoint": 100,
      "isEarned": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:30.000Z"
    },
    {
      "id": "prog_earning_002",
      "title": "Place Order",
      "type": "earning",
      "event": "place_order",
      "earnPoint": 10,
      "createdAt": "2024-01-16T08:00:00.000Z",
      "updatedAt": "2024-01-21T10:15:00.000Z"
    },
    {
      "id": "prog_earning_003",
      "title": "Follow Instagram",
      "type": "earning",
      "event": "follow_instagram",
      "earnPoint": 50,
      "isEarned": false,
      "createdAt": "2024-01-16T12:00:00.000Z",
      "updatedAt": "2024-01-21T16:30:00.000Z"
    }
  ]
}

Calculate earning points

POST/rest_api/v2/programs/earning/points/calculate

Calculate points that would be earned for given products

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Request body

productsobject[]Required

Show properties

idstringOptional

quantityintegerOptional

pricenumberOptional

shopifyCustomerIdstringOptional

sourceNamestringOptional

Responses

200Calculated points

successbooleanOptional

Example: true

dataobjectOptional

Show properties

pointsEarnintegerOptional

productsobject[]Optional

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/programs/earning/points/calculate

POST /rest_api/v2/programs/earning/points/calculate 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: 154

{
  "products": [
    {
      "id": "string",
      "quantity": 1,
      "price": 1
    }
  ],
  "shopifyCustomerId": "string",
  "sourceName": "string"
}

200Calculated points

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

Handle social earning interactions

POST/rest_api/v2/programs/earning/social/interactions

Process social media interactions for earning points

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Request body

shopifyCustomerIdstringRequired

eventstringOptional

earningIdstringOptional

Responses

200Social earning processed

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/programs/earning/social/interactions

POST /rest_api/v2/programs/earning/social/interactions 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: 81

{
  "shopifyCustomerId": "string",
  "event": "string",
  "earningId": "string"
}

200Social earning processed

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

Get redemption programs

GET/rest_api/v2/programs/redemption

Retrieve all point spending/redemption programs

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Parameters

shopifyCustomerIdquery · stringOptional

Shopify customer ID for program limitations

eventquery · stringOptional

Filter by program event type

Responses

200List of spending programs

successbooleanOptional

Example: true

dataProgram[]Optional

Show properties

idstringOptional

Example: "prog_abc123"

titlestringOptional

Example: "Sign Up Bonus"

typestringOptional

Example: "earning"

eventstringOptional

Example: "sign_up"

statusbooleanOptional

Example: true

priorityintegerOptional

Example: 1

createdAtstring · date-timeOptional

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

updatedAtstring · date-timeOptional

Example: "2024-01-20T14:45:30.000Z"

expiredbooleanOptional

Example: false

isDraftbooleanOptional

Example: false

earnBystringOptional

Example: "price"

rateMoneynumberOptional

Example: 1

earnPointintegerOptional

Example: 100

startDatestring · date-timeOptional

Example: "2024-01-01T00:00:00.000Z"

endDatestring · date-timeOptional

Example: "2024-12-31T23:59:59.000Z"

autoRemovePointsbooleanOptional

Example: false

appliedPlaceOrderTostringOptional

Example: "all"

appliedSourcestring[]Optional

Example: ["web","pos"]

translateTitleobjectOptional

Example: {}

typeMilestonestringOptional

Example: null

milestonesobject[]Optional

Example: []

spendPointintegerOptional

Example: 500

earnAmountnumberOptional

Example: 10

redeemTypestringOptional

Example: "amount_discount"

appliedTostringOptional

Example: "all"

appliedCollectionIdsstring[]Optional

Example: []

redeemInstringOptional

Example: "available_in_online_store"

orderReqstringOptional

Example: "none"

orderReqAmountnumberOptional

Example: 0

minSpendPointstringOptional

Example: ""

maxSpendPointstringOptional

Example: ""

expiredTimestringOptional

Example: ""

userAvailabilitystringOptional

Example: "userRedeemed"

showLoyaltyPagebooleanOptional

Example: true

limitRedeemstringOptional

Example: "redeemWithoutLimit"

totalLimitationRedeemintegerOptional

Example: 0

combinedWithstring[]Optional

Example: []

specificProductsobject[]Optional

Example: []

specificProductIdsstring[]Optional

Example: []

specificCollectionsobject[]Optional

Example: []

variantIdsstring[]Optional

Example: []

freeProductIdsstring[]Optional

Example: []

giftStatusstringOptional

Example: "none"

excludeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

includeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

conditionsobject[]Optional

earnPointsTiersobject[]Optional

Show properties

earnPointintegerOptional

rateMoneynumberOptional

roundingMethodstringOptional

Example: "round"

skipEarnPointGuestbooleanOptional

Example: false

metaobjectOptional

Show properties

countintegerOptional

Number of items returned

messagestringOptional

Example: "Operation completed successfully"

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

GET/rest_api/v2/programs/redemption

GET /rest_api/v2/programs/redemption 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: */*

200List of spending programs

{
  "success": true,
  "data": [
    {
      "id": "aYorhxYUTkUKIDZgL1R5",
      "title": "Free Product Test",
      "type": "spending",
      "event": "free_gift",
      "status": true,
      "spendPoint": 200,
      "earnAmount": 700,
      "priority": 0,
      "redeemType": "fixed",
      "appliedTo": "sf_product",
      "redeemIn": "available_in_online_store",
      "expiredTime": "",
      "userAvailability": "userRedeemed",
      "showLoyaltyPage": true,
      "limitRedeem": "redeemWithoutLimit",
      "totalLimitationRedeem": 0,
      "combinedWith": [
        "orderDiscounts",
        "productDiscounts",
        "shippingDiscounts"
      ],
      "specificProductIds": [
        44438017147115,
        44438017114347
      ],
      "variantIds": [
        44438017147115,
        44438017179883,
        44438017245419,
        44438017114347
      ],
      "specificProducts": [
        {
          "id": 8209413669099,
          "title": "The Complete Snowboard",
          "handle": "the-complete-snowboard",
          "image": {
            "src": "https://cdn.shopify.com/s/files/1/0680/3950/8203/products/Main_589fc064-24a2-4236-9eaf-13b2bd35d21d.jpg?v=1703045153"
          }
        }
      ],
      "giftStatus": "none",
      "expired": false,
      "isDraft": false,
      "createdAt": "2024-08-27T08:09:46.757Z",
      "updatedAt": "2025-06-18T08:13:55.797Z"
    },
    {
      "id": "vIswMZYogmKyw94GzEvn",
      "title": "Points for discounts",
      "type": "spending",
      "event": "amount_discount",
      "status": true,
      "spendPoint": 100,
      "earnAmount": "5",
      "priority": 3,
      "redeemType": "fixed",
      "appliedTo": "sf_product",
      "orderReq": "none",
      "orderReqAmount": 0,
      "expiredTime": "",
      "userAvailability": "userRedeemed",
      "showLoyaltyPage": true,
      "limitRedeem": "redeemWithoutLimit",
      "combinedWith": [],
      "specificProductIds": [
        44438017114347
      ],
      "conditions": [
        {
          "type": "criteria_customer",
          "field": "customer_country_code",
          "typeMatch": "equal"
        }
      ],
      "giftStatus": "none",
      "expired": false,
      "isDraft": false,
      "createdAt": "2024-10-14T04:36:02.987Z",
      "updatedAt": "2025-06-18T08:13:55.283Z"
    }
  ]
}

Create spending/redemption program

POST/rest_api/v2/programs/redemption

Create a new spending/redemption program. The event field determines the redemption type.

Event Types & Required Fields

amount_discount / percentage_discount:

Required: title, event, spendPoint (positive int), earnAmount (discount value; for percentage must be < 100)
Optional: redeemType (fixed|dynamic, default: "fixed"). Dynamic mode (amount_discount only) lets customer choose points to spend within min/max range.
Dynamic mode fields:
- hasMinSpend, minSpendPoint (must be divisible by spendPoint)
- hasMaxSpend, maxSpendPoint (must be >= spendPoint, divisible by spendPoint)
- hasLimitCartValue, limitCartValue (1-100, max % of cart)
Product scope (appliedTo):
- all — no extra fields
- specific or exclude_collection — requires appliedCollectionIds
- sf_product — requires specificProducts (max 100)
Order requirements (orderReq):
- none — no requirement
- min_amount — requires orderReqAmount
- min_quantity — requires orderReqQuantity
Expiration: expiredAfter (permanent|7D|14D|1M|3M|6M|1Y|2Y|specific). When "specific": expiredTime required.
Combination: combinedWith (array of orderDiscounts|productDiscounts|shippingDiscounts).
Availability: userAvailability (allUsers|userRedeemed|userInSegment). When "userInSegment": appliedSegments required.
Channel: appliedDiscountToSaleChannel (applyOnlineStore|applyPos|applyAll).

free_shipping:

Required: title, event, spendPoint, shippingDiscountType (percentage|fixedAmount), shippingDiscountAmount (for percentage, must be <= 100)
Optional: hasLimitShipping, limitShipping (max shipping cost), destination (all|countries), selectedCountries.
Note: combinedWith cannot include "shippingDiscounts" (this IS a shipping discount).

free_gift:

Required: title, event, spendPoint, appliedTo (sf_product|specific|exclude_collection — "all" NOT allowed)
Scope depends on appliedTo:
- sf_product — requires specificProducts (1-100 items)
- specific or exclude_collection — requires appliedCollectionIds + collectionQuantity
Optional: variantIds, freeGiftPriceSelection (highest|lowest), freeProductQuantity (all|one).

buy_x_get_y:

Required: title, event, spendPoint
Buy-side:
- orderReqQuantity (buy X items)
- appliedTo (specific | sf_product — "all" NOT allowed)
- specific → appliedCollectionIds required
- sf_product → specificProducts required
Get-side:
- orderGetQuantity (get Y items)
- appliedToGets (specific | sf_product)
- specific → appliedCollectionIdsGets required
- sf_product → specificProductsGets required
discountedType (percentage | amount | free). When percentage/amount → discountedValue required.

custom_voucher: (hidden feature, not recommended)

Required: title, event, spendPoint
Optional: descriptionHtml, imageUrl, newVouchers (array of voucher codes), voucherLimitRedeem.

Shared Optional Fields

status (default: true), priority, isDraft, prefix, isUsePrefixDiscountCode, showLoyaltyPage
hasLimit, limitUnit, limitInterval — redemption frequency cap
usageLimit, appliesOncePerCustomer — Shopify discount usage limits
customerEligibility (eligible_all|eligible_tier_customer), tiersEligible

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Request body

titlestringRequired

Program display title shown to customers.

eventstringRequired

Spending event type. Determines required fields and validation rules.

statusbooleanOptional

Whether the program is active.

spendPointintegerOptional

Points required to redeem. Required for all events.

earnAmountnumberOptional

Discount value. Required for amount_discount/percentage_discount. For percentage, must be < 100.

redeemTypestringOptional

fixed: set points for set discount. dynamic: customer chooses within min/max range.

shippingDiscountTypestringOptional

Required for free_shipping.

shippingDiscountAmountnumberOptional

Shipping discount value. Required for free_shipping. For percentage, must be <= 100.

appliedTostringOptional

Product scope. For free_gift: 'all' NOT allowed.

appliedCollectionIdsstring[]Optional

Collection IDs. Required when appliedTo is 'specific' or 'exclude_collection'.

specificProductsobject[]Optional

Product objects (max 100). Required when appliedTo is 'sf_product'.

orderReqstringOptional

Order requirement to use reward. 'min_amount': customer order must exceed orderReqAmount. 'min_quantity': order must have at least orderReqQuantity items.

orderReqAmountnumberOptional

Min order amount. Required when orderReq='min_amount'.

orderReqQuantityintegerOptional

Min item quantity. Required when orderReq='min_quantity'. For buy_x_get_y: number of items customer must buy.

orderGetQuantityintegerOptional

Number of free/discounted items customer gets. Required for buy_x_get_y.

appliedToGetsstringOptional

Get-side product scope for buy_x_get_y. 'specific': use appliedCollectionIdsGets. 'sf_product': use specificProductsGets.

discountedTypestringOptional

Discount applied to get-side items. 'free': 100% off. 'percentage'/'amount': requires discountedValue. Required for buy_x_get_y.

discountedValuenumberOptional

Discount value on get-side items. Required when discountedType is 'percentage' or 'amount'.

expiredAfterstringOptional

Coupon expiration period. 'permanent': never expires. 'specific': use expiredTime for exact datetime.

combinedWithstring[]Optional

Allow combining with other Shopify discount types. For free_shipping: cannot include 'shippingDiscounts'.

appliedDiscountToSaleChannelstringOptional

Which sales channels the coupon is valid on.

userAvailabilitystringOptional

Who can redeem. 'allUsers': everyone. 'userRedeemed': only loyalty members. 'userInSegment': requires appliedSegments.

priorityintegerOptional

Program display order. Lower = higher priority.

isDraftbooleanOptional

Save as draft without activating.

prefixstringOptional

Discount code prefix.

isUsePrefixDiscountCodebooleanOptional

Whether to use prefix for discount codes.

showLoyaltyPagebooleanOptional

Show on loyalty/rewards page.

expiredTimestringOptional

Specific expiration datetime. Required when expiredAfter='specific'.

purchaseTypestringOptional

Which purchase types the discount applies to. Only visible when shop.enableDiscountSubscription is enabled. For amount_discount/percentage_discount.

conditionsobject[]Optional

Advanced discount conditions. Customer-level conditions for all events; order-level (order_shipping_method) only for free_shipping. Requires Advanced plan.

Show properties

typestringOptional

typeMatchstringOptional

fieldstringOptional

contentobjectOptional

isRedeemCheckOutbooleanOptional

Allow checkout-page redemption. Requires Shopify Plus and Enterprise/Pro plan.

enabledExcludePOSbooleanOptional

Exclude specific POS locations.

excludeLocationsPOSstring[]Optional

POS location IDs to exclude.

showChannelstringOptional

Where the program is displayed. For POS-enabled programs.

isAppliedVipTierbooleanOptional

Restrict to specific VIP tiers. For amount_discount/percentage_discount.

appliedTiersstring[]Optional

Tier IDs that can access this program. Used when isAppliedVipTier=true.

earnPointsTiersobjectOptional

Per-tier overrides for spend/earn values. Format: { [tierId]: { earnPoint, spendPoint, earnAmount } }. Used when isAppliedVipTier=true.

hasMinSpendbooleanOptional

Enable minimum spend in dynamic mode. For amount_discount with redeemType='dynamic'.

minSpendPointintegerOptional

Min points to spend (must be divisible by spendPoint). Required when hasMinSpend=true.

hasMaxSpendbooleanOptional

Enable maximum spend in dynamic mode.

maxSpendPointintegerOptional

Max points (must be >= spendPoint, divisible by spendPoint). Required when hasMaxSpend=true.

hasLimitCartValuebooleanOptional

Limit discount to percentage of cart value.

limitCartValueintegerOptional

Max percentage of cart value for discount (1-100). Required when hasLimitCartValue=true.

blockLimitedCouponReusebooleanOptional

Prevent reuse of cart-value-limited coupons on smaller carts. Recommended when hasLimitCartValue=true.

hasLimitShippingbooleanOptional

Apply only to shipping rates below max cost. For free_shipping.

limitShippingintegerOptional

Max shipping cost. Required when hasLimitShipping=true.

destinationstringOptional

Shipping destination scope. For free_shipping.

selectedCountriesobject[]Optional

Country filter. Required when destination='countries'.

specificProductIdsstring[]Optional

Product variant IDs for the buy side. Required when appliedTo='sf_product' for buy_x_get_y.

specificCollectionsobject[]Optional

Collection objects (for display). Used alongside appliedCollectionIds.

Show properties

idstringOptional

titlestringOptional

variantIdsstring[]Optional

Specific variant IDs (max 100). For free_gift with appliedTo='sf_product'.

freeGiftPriceSelectionstringOptional

Which product price to select from collection. For free_gift with appliedTo='specific'/'exclude_collection'.

freeProductQuantitystringOptional

Whether customer gets all listed products or picks one. For free_gift.

collectionQuantityintegerOptional

Total quantity of free products across collections. Required for free_gift when appliedTo='specific'/'exclude_collection'.

appliedCollectionIdsGetsstring[]Optional

Get-side collection IDs. Required when appliedToGets='specific'.

specificProductsGetsobject[]Optional

Get-side products (max 100). Required when appliedToGets='sf_product'.

specificProductIdsGetsstring[]Optional

Get-side product variant IDs. Required when appliedToGets='sf_product'.

specificCollectionsGetsobject[]Optional

Get-side collection objects (for display). Used alongside appliedCollectionIdsGets.

enableMaximumUsesPerOrderbooleanOptional

Cap uses per order. For buy_x_get_y.

maximumUsesPerOrderintegerOptional

Max uses per order. Required when enableMaximumUsesPerOrder=true.

descriptionHtmlstringOptional

Rich-text HTML description shown to customers. For custom_voucher.

imageUrlstringOptional

Voucher image URL. For custom_voucher.

newVouchersstring[]Optional

Voucher codes to import (duplicates auto-removed, existing codes skipped). For custom_voucher.

voucherLimitRedeemintegerOptional

Max vouchers a single customer can redeem. null/omit = unlimited. For custom_voucher.

expDateFromstringOptional

Start date for voucher redemption period (ISO 8601). For custom_voucher.

expDateTostringOptional

End date for voucher redemption period (ISO 8601). Must be after expDateFrom. For custom_voucher.

appliedSegmentsobject[]Optional

Segment filter. Required when userAvailability='userInSegment'.

usageLimitintegerOptional

Shopify discount usage limit.

appliesOncePerCustomerbooleanOptional

Limit to one use per customer.

customerEligibilitystringOptional

Customer eligibility filter.

tiersEligiblestring[]Optional

Tier IDs. Required when customerEligibility='eligible_tier_customer'.

hasLimitbooleanOptional

Enable redemption frequency cap.

limitUnitstringOptional

Time unit for frequency cap.

limitIntervalintegerOptional

Number of limitUnit periods between redemptions. Required when hasLimit=true AND limitUnit != 'lifetime'.

limitRedeemstringOptional

Global redemption limit type.

totalLimitationRedeemintegerOptional

Total redemption limit. Required when limitRedeem='redeemLimit'.

Responses

201Program created successfully

successbooleanOptional

Example: true

dataProgramOptional

Loyalty program (earning or spending) 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

Example: "prog_abc123"

titlestringOptional

Example: "Sign Up Bonus"

typestringOptional

Example: "earning"

eventstringOptional

Example: "sign_up"

statusbooleanOptional

Example: true

priorityintegerOptional

Example: 1

createdAtstring · date-timeOptional

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

updatedAtstring · date-timeOptional

Example: "2024-01-20T14:45:30.000Z"

expiredbooleanOptional

Example: false

isDraftbooleanOptional

Example: false

earnBystringOptional

Example: "price"

rateMoneynumberOptional

Example: 1

earnPointintegerOptional

Example: 100

startDatestring · date-timeOptional

Example: "2024-01-01T00:00:00.000Z"

endDatestring · date-timeOptional

Example: "2024-12-31T23:59:59.000Z"

autoRemovePointsbooleanOptional

Example: false

appliedPlaceOrderTostringOptional

Example: "all"

appliedSourcestring[]Optional

Example: ["web","pos"]

translateTitleobjectOptional

Example: {}

typeMilestonestringOptional

Example: null

milestonesobject[]Optional

Example: []

spendPointintegerOptional

Example: 500

earnAmountnumberOptional

Example: 10

redeemTypestringOptional

Example: "amount_discount"

appliedTostringOptional

Example: "all"

appliedCollectionIdsstring[]Optional

Example: []

redeemInstringOptional

Example: "available_in_online_store"

orderReqstringOptional

Example: "none"

orderReqAmountnumberOptional

Example: 0

minSpendPointstringOptional

Example: ""

maxSpendPointstringOptional

Example: ""

expiredTimestringOptional

Example: ""

userAvailabilitystringOptional

Example: "userRedeemed"

showLoyaltyPagebooleanOptional

Example: true

limitRedeemstringOptional

Example: "redeemWithoutLimit"

totalLimitationRedeemintegerOptional

Example: 0

combinedWithstring[]Optional

Example: []

specificProductsobject[]Optional

Example: []

specificProductIdsstring[]Optional

Example: []

specificCollectionsobject[]Optional

Example: []

variantIdsstring[]Optional

Example: []

freeProductIdsstring[]Optional

Example: []

giftStatusstringOptional

Example: "none"

excludeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

includeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

conditionsobject[]Optional

earnPointsTiersobject[]Optional

Show properties

earnPointintegerOptional

rateMoneynumberOptional

roundingMethodstringOptional

Example: "round"

skipEarnPointGuestbooleanOptional

Example: false

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional

Example: "Operation completed successfully"

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

400Validation error — missing required fields, invalid values, or cross-field constraint violations

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

POST/rest_api/v2/programs/redemption

POST /rest_api/v2/programs/redemption 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: 317

{
  "title": "Points for $5 off",
  "event": "amount_discount",
  "spendPoint": 100,
  "earnAmount": 5,
  "redeemType": "fixed",
  "appliedTo": "all",
  "orderReq": "min_amount",
  "orderReqAmount": 25,
  "expiredAfter": "3M",
  "combinedWith": [
    "shippingDiscounts"
  ],
  "prefix": "REWARD-",
  "status": true
}

201Program created successfully

{
  "success": true,
  "data": {
    "id": "xK9mNpQ2wR4vT7yB3jL6",
    "title": "Points for $5 off",
    "type": "spending",
    "event": "amount_discount",
    "status": true,
    "spendPoint": 100,
    "earnAmount": 5,
    "priority": 0,
    "redeemType": "fixed",
    "appliedTo": "all",
    "orderReq": "min_amount",
    "orderReqAmount": 25,
    "expiredAfter": "3M",
    "userAvailability": "userRedeemed",
    "showLoyaltyPage": true,
    "combinedWith": [
      "shippingDiscounts"
    ],
    "appliedDiscountToSaleChannel": "applyOnlineStore",
    "purchaseType": "one_time_purchase",
    "prefix": "REWARD-",
    "isUsePrefixDiscountCode": true,
    "isDraft": false,
    "createdAt": "2026-03-24T10:30:00.000Z",
    "updatedAt": "2026-03-24T10:30:00.000Z"
  },
  "meta": {},
  "timestamp": "2026-03-24T10:30:00.123Z"
}

Get program by ID

GET/rest_api/v2/programs/{programId}

Retrieve a specific program by its ID

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Parameters

programIdpath · stringRequired

Program ID

shopifyCustomerIdquery · stringOptional

Shopify customer ID for program limitations

Responses

200Program details

successbooleanOptional

Example: true

dataProgramOptional

Loyalty program (earning or spending) 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

Example: "prog_abc123"

titlestringOptional

Example: "Sign Up Bonus"

typestringOptional

Example: "earning"

eventstringOptional

Example: "sign_up"

statusbooleanOptional

Example: true

priorityintegerOptional

Example: 1

createdAtstring · date-timeOptional

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

updatedAtstring · date-timeOptional

Example: "2024-01-20T14:45:30.000Z"

expiredbooleanOptional

Example: false

isDraftbooleanOptional

Example: false

earnBystringOptional

Example: "price"

rateMoneynumberOptional

Example: 1

earnPointintegerOptional

Example: 100

startDatestring · date-timeOptional

Example: "2024-01-01T00:00:00.000Z"

endDatestring · date-timeOptional

Example: "2024-12-31T23:59:59.000Z"

autoRemovePointsbooleanOptional

Example: false

appliedPlaceOrderTostringOptional

Example: "all"

appliedSourcestring[]Optional

Example: ["web","pos"]

translateTitleobjectOptional

Example: {}

typeMilestonestringOptional

Example: null

milestonesobject[]Optional

Example: []

spendPointintegerOptional

Example: 500

earnAmountnumberOptional

Example: 10

redeemTypestringOptional

Example: "amount_discount"

appliedTostringOptional

Example: "all"

appliedCollectionIdsstring[]Optional

Example: []

redeemInstringOptional

Example: "available_in_online_store"

orderReqstringOptional

Example: "none"

orderReqAmountnumberOptional

Example: 0

minSpendPointstringOptional

Example: ""

maxSpendPointstringOptional

Example: ""

expiredTimestringOptional

Example: ""

userAvailabilitystringOptional

Example: "userRedeemed"

showLoyaltyPagebooleanOptional

Example: true

limitRedeemstringOptional

Example: "redeemWithoutLimit"

totalLimitationRedeemintegerOptional

Example: 0

combinedWithstring[]Optional

Example: []

specificProductsobject[]Optional

Example: []

specificProductIdsstring[]Optional

Example: []

specificCollectionsobject[]Optional

Example: []

variantIdsstring[]Optional

Example: []

freeProductIdsstring[]Optional

Example: []

giftStatusstringOptional

Example: "none"

excludeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

includeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

conditionsobject[]Optional

earnPointsTiersobject[]Optional

Show properties

earnPointintegerOptional

rateMoneynumberOptional

roundingMethodstringOptional

Example: "round"

skipEarnPointGuestbooleanOptional

Example: false

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional

Example: "Operation completed successfully"

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

404Program not found

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

GET/rest_api/v2/programs/{programId}

GET /rest_api/v2/programs/{programId} 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: */*

200Program details

{
  "success": true,
  "data": {
    "id": "aYorhxYUTkUKIDZgL1R5",
    "title": "Free Product Test",
    "type": "spending",
    "event": "free_gift",
    "status": true,
    "spendPoint": 200,
    "earnAmount": 700,
    "priority": 0,
    "redeemType": "fixed",
    "appliedTo": "sf_product",
    "redeemIn": "available_in_online_store",
    "expiredTime": "",
    "userAvailability": "userRedeemed",
    "showLoyaltyPage": true,
    "limitRedeem": "redeemWithoutLimit",
    "totalLimitationRedeem": 0,
    "combinedWith": [
      "orderDiscounts",
      "productDiscounts",
      "shippingDiscounts"
    ],
    "specificProductIds": [
      44438017147115,
      44438017114347
    ],
    "variantIds": [
      44438017147115,
      44438017179883,
      44438017245419,
      44438017114347
    ],
    "specificProducts": [
      {
        "id": 8209413669099,
        "title": "The Complete Snowboard",
        "handle": "the-complete-snowboard",
        "image": {
          "src": "https://cdn.shopify.com/s/files/1/0680/3950/8203/products/Main_589fc064-24a2-4236-9eaf-13b2bd35d21d.jpg?v=1703045153"
        },
        "variants": [
          {
            "id": 44438017147115,
            "price": "700",
            "title": "Ice",
            "inventory_quantity": 10
          }
        ]
      }
    ],
    "giftStatus": "none",
    "expired": false,
    "isDraft": false,
    "createdAt": "2024-08-27T08:09:46.757Z",
    "updatedAt": "2025-06-18T08:13:55.797Z"
  }
}

Update program

PUT/rest_api/v2/programs/{programId}

Partial update — send only the fields you want to change. The endpoint looks up the program, determines its type (earning or spending), and filters the update body to only fields allowed for that type. Unrecognized or readonly fields are silently ignored.

Behavior

Readonly fields stripped: id, type, shopId, createdAt, updatedAt are always ignored — you cannot change a program's type or ID.
Field whitelist applied: Only fields in earningProgramFields (for earning) or spendingProgramFields (for spending) pass through. Other fields are silently dropped.
Empty body rejected: Returns 400 UPDATE_DATA_REQUIRED if the request body is empty.
No valid fields rejected: Returns 400 INVALID_UPDATE_FIELDS if all provided fields were readonly or not in the whitelist.
Response: Returns the full updated program (re-fetched after save), with null fields filtered out and dates formatted.

Updatable Fields by Program Type

Earning programs — any field from earningProgramFields (see POST /programs/earning):

Category	Fields
Basic	`title`, `status`, `earnPoint`, `priority`, `isDraft`, `startDate`, `endDate`
Purchase	`earnBy`, `rateMoney`, `autoRemovePoints`, `appliedPlaceOrderTo`, `appliedSource`, `excludeProducts`, `includeProducts`, `conditions`, `roundingMethod`, `skipEarnPointGuest`
Social	`urlAccount`, `enabledAntiCheat`, `message`, `typeJoin`, `imageQRCode`
Review	`reviewApp`, `descriptionReview`, `isAppliedExtraPoints`, `extraPoints`
Frequency	`hasLimit`, `limitUnit`, `limitInterval`
VIP Tier	`isAppliedVipTier`, `earnPointsTiers`
Discount (typeEarn != point)	`prefix`, `isUsePrefixDiscountCode`, `appliedTo`, `appliedCollectionIds`, `specificProducts`, `orderReq`, `orderReqAmount`, `expiredAfter`, `expiredTime`, `combinedWith`, `appliedDiscountToSaleChannel`, `userAvailability`

Spending programs — any field from spendingProgramFields (see POST /programs/redemption):

Category	Fields
Basic	`title`, `status`, `spendPoint`, `earnAmount`, `redeemType`, `priority`, `isDraft`
Product scope	`appliedTo`, `appliedCollectionIds`, `specificProducts`, `specificProductIds`, `specificCollections`, `variantIds`
Order requirements	`orderReq`, `orderReqAmount`, `orderReqQuantity`
Dynamic mode	`minSpendPoint`, `maxSpendPoint`, `hasMinSpend`, `hasMaxSpend`, `hasLimitCartValue`, `limitCartValue`
Expiration	`expiredAfter`, `expiredTime`
Limits	`limitRedeem`, `totalLimitationRedeem`, `usageLimit`, `appliesOncePerCustomer`, `blockLimitedCouponReuse`, `hasLimit`, `limitInterval`, `limitUnit`
Availability	`userAvailability`, `appliedSegments`, `customerEligibility`, `tiersEligible`, `showLoyaltyPage`
Discount config	`combinedWith`, `appliedDiscountToSaleChannel`, `purchaseType`, `prefix`, `isUsePrefixDiscountCode`, `isRedeemCheckOut`, `enabledExcludePOS`, `excludeLocationsPOS`

Important Notes

You cannot change event or type — these are set at creation time.
No cross-field validation is applied on update (unlike create). The provided fields are saved as-is.
For spending programs, spendPoint is cast to integer in the response via prepareProgramData.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Parameters

programIdpath · stringRequired

Program ID

Request body

titlestringOptional

Program display title.

statusbooleanOptional

Enable/disable the program.

earnPointnumberOptional

Points to award. For earning programs.

spendPointintegerOptional

Points required to redeem. For spending programs.

earnAmountnumberOptional

Discount value. For spending programs (amount_discount, percentage_discount).

priorityintegerOptional

Program display/sort priority.

isDraftbooleanOptional

Toggle draft mode.

earnBystringOptional

Earning method. For place_order programs.

rateMoneynumberOptional

Currency-to-points ratio. For place_order with earnBy=price/fixed_order.

urlAccountstringOptional

Social media URL. For social earning programs.

startDatestring · date-timeOptional

Program start date (ISO 8601). For earning programs.

endDatestring · date-timeOptional

Program end date (ISO 8601). For earning programs.

autoRemovePointsbooleanOptional

Remove points on refund. For place_order.

roundingMethodstringOptional

Point rounding. For place_order.

skipEarnPointGuestbooleanOptional

Skip guest earning. For place_order.

redeemTypestringOptional

Redemption mode. For amount_discount.

appliedTostringOptional

Product scope. For discount/free_gift programs.

appliedCollectionIdsstring[]Optional

Collection IDs. For programs with appliedTo=specific.

specificProductsobject[]Optional

Product objects. For programs with appliedTo=sf_product.

orderReqstringOptional

Order requirement.

orderReqAmountnumberOptional

Minimum order amount.

expiredAfterstringOptional

Coupon expiration. For spending programs.

expiredTimestringOptional

Specific expiration datetime.

combinedWithstring[]Optional

Discount combination rules.

appliedDiscountToSaleChannelstringOptional

Sales channel for discount.

userAvailabilitystringOptional

Who can use the discount.

purchaseTypestringOptional

Purchase type filter.

usageLimitintegerOptional

Shopify discount usage limit. null = unlimited.

appliesOncePerCustomerbooleanOptional

Limit to one use per customer.

hasLimitbooleanOptional

Enable earning/redeem frequency cap.

limitUnitstringOptional

Frequency cap time unit.

limitIntervalintegerOptional

Frequency cap interval.

isAppliedVipTierbooleanOptional

Enable VIP tier restrictions.

earnPointsTiersobjectOptional

Per-tier earn/spend overrides.

prefixstringOptional

Discount code prefix.

isUsePrefixDiscountCodebooleanOptional

Whether to use prefix.

isRedeemCheckOutbooleanOptional

Allow checkout-page redemption.

enabledExcludePOSbooleanOptional

Exclude POS locations.

excludeLocationsPOSstring[]Optional

POS location IDs to exclude.

customerEligibilitystringOptional

Customer eligibility filter. For spending programs.

tiersEligiblestring[]Optional

Tier IDs for eligibility.

conditionsobject[]Optional

Advanced conditions.

showLoyaltyPagebooleanOptional

Show on loyalty page.

hasMinSpendbooleanOptional

Enable min spend (dynamic discount).

hasMaxSpendbooleanOptional

Enable max spend (dynamic discount).

minSpendPointintegerOptional

Minimum points to spend.

maxSpendPointintegerOptional

Maximum points to spend.

hasLimitCartValuebooleanOptional

Limit discount to % of cart.

limitCartValueintegerOptional

Max % of cart value (1-100).

blockLimitedCouponReusebooleanOptional

Prevent cart-limited coupon reuse.

appliedSegmentsobject[]Optional

Customer segments for userInSegment.

Responses

200Program updated successfully. Returns the full updated program.

successbooleanOptional

Example: true

dataProgramOptional

Loyalty program (earning or spending) 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

Example: "prog_abc123"

titlestringOptional

Example: "Sign Up Bonus"

typestringOptional

Example: "earning"

eventstringOptional

Example: "sign_up"

statusbooleanOptional

Example: true

priorityintegerOptional

Example: 1

createdAtstring · date-timeOptional

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

updatedAtstring · date-timeOptional

Example: "2024-01-20T14:45:30.000Z"

expiredbooleanOptional

Example: false

isDraftbooleanOptional

Example: false

earnBystringOptional

Example: "price"

rateMoneynumberOptional

Example: 1

earnPointintegerOptional

Example: 100

startDatestring · date-timeOptional

Example: "2024-01-01T00:00:00.000Z"

endDatestring · date-timeOptional

Example: "2024-12-31T23:59:59.000Z"

autoRemovePointsbooleanOptional

Example: false

appliedPlaceOrderTostringOptional

Example: "all"

appliedSourcestring[]Optional

Example: ["web","pos"]

translateTitleobjectOptional

Example: {}

typeMilestonestringOptional

Example: null

milestonesobject[]Optional

Example: []

spendPointintegerOptional

Example: 500

earnAmountnumberOptional

Example: 10

redeemTypestringOptional

Example: "amount_discount"

appliedTostringOptional

Example: "all"

appliedCollectionIdsstring[]Optional

Example: []

redeemInstringOptional

Example: "available_in_online_store"

orderReqstringOptional

Example: "none"

orderReqAmountnumberOptional

Example: 0

minSpendPointstringOptional

Example: ""

maxSpendPointstringOptional

Example: ""

expiredTimestringOptional

Example: ""

userAvailabilitystringOptional

Example: "userRedeemed"

showLoyaltyPagebooleanOptional

Example: true

limitRedeemstringOptional

Example: "redeemWithoutLimit"

totalLimitationRedeemintegerOptional

Example: 0

combinedWithstring[]Optional

Example: []

specificProductsobject[]Optional

Example: []

specificProductIdsstring[]Optional

Example: []

specificCollectionsobject[]Optional

Example: []

variantIdsstring[]Optional

Example: []

freeProductIdsstring[]Optional

Example: []

giftStatusstringOptional

Example: "none"

excludeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

includeProductsobject[]Optional

Show properties

idstringOptional

titlestringOptional

imageobjectOptional

Show properties

srcstringOptional

conditionsobject[]Optional

earnPointsTiersobject[]Optional

Show properties

earnPointintegerOptional

rateMoneynumberOptional

roundingMethodstringOptional

Example: "round"

skipEarnPointGuestbooleanOptional

Example: false

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional

Example: "Operation completed successfully"

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

400Invalid update data or no valid fields for program type

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

404Program not found

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

PUT/rest_api/v2/programs/{programId}

PUT /rest_api/v2/programs/{programId} 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: 22

{
  "earnPoint": 200
}

200Program updated successfully. Returns the full updated program.

{
  "success": true,
  "data": {
    "id": "vIswMZYogmKyw94GzEvn",
    "title": "Points for discounts",
    "type": "spending",
    "event": "amount_discount",
    "status": true,
    "spendPoint": 200,
    "earnAmount": 10,
    "priority": 3,
    "redeemType": "fixed",
    "appliedTo": "all",
    "orderReq": "none",
    "expiredAfter": "6M",
    "userAvailability": "userRedeemed",
    "showLoyaltyPage": true,
    "combinedWith": [],
    "appliedDiscountToSaleChannel": "applyOnlineStore",
    "purchaseType": "one_time_purchase",
    "isDraft": false,
    "createdAt": "2024-10-14T04:36:02.987Z",
    "updatedAt": "2026-03-24T11:00:00.000Z"
  },
  "meta": {},
  "timestamp": "2026-03-24T11:00:00.123Z"
}

Delete program (hard delete)

DELETE/rest_api/v2/programs/{programId}

Permanently removes a program from the database. This action cannot be undone.

The response includes the full program data as it existed before deletion, allowing the caller to store a backup if needed.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Parameters

programIdpath · stringRequired

Program ID

Responses

200Program deleted successfully

successbooleanOptional

Example: true

dataobjectOptional

Full program data as it existed before deletion

Show properties

idstringOptional

titlestringOptional

eventstringOptional

typestringOptional

statusbooleanOptional

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional

Example: "Operation completed successfully"

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

404Program not found

successbooleanOptional

Example: false

errorobjectOptional

Show properties

messagestringOptional

Example: "Resource not found"

codestringOptional

Example: "NOT_FOUND"

statusCodeintegerOptional

Example: 404

detailsobjectOptional

timestampstring · date-timeOptional

Example: "2023-07-28T07:27:54.123Z"

DELETE/rest_api/v2/programs/{programId}

DELETE /rest_api/v2/programs/{programId} 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: */*

200Program deleted successfully

{
  "success": true,
  "data": {
    "id": "prog_abc123",
    "title": "Earn on Purchase",
    "event": "place_order",
    "type": "earning",
    "status": true
  },
  "message": "Program deleted successfully"
}

Redeem points for rewards

POST/rest_api/v2/programs/redemption/redeem

Redeem customer points for rewards through a redemption program

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Request body

programIdstringRequired

shopifyCustomerIdstringRequired

quantityintegerOptional

Responses

200Redemption successful

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/programs/redemption/redeem

POST /rest_api/v2/programs/redemption/redeem 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: 77

{
  "programId": "string",
  "shopifyCustomerId": "string",
  "quantity": 1
}

200Redemption successful

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

API references Customers