{ "components": { "schemas": { "CheckDiscountRequest": { "description": "Request containing customer ID and discount code to validate", "example": { "customerId": 67890, "discountCode": "LOYALTY15OFF" }, "properties": { "customerId": { "description": "Shopify customer ID (numeric). Identifies which customer is attempting to use the discount code.\nUsed to verify the discount code belongs to this customer.\nExample: 67890\n", "example": 67890, "format": "int64", "type": "integer" }, "discountCode": { "description": "The discount code to validate. Case-insensitive.\nThis is the code the customer enters at checkout.\nSystem will check if:\n- Code exists in loyalty system\n- Code belongs to this customer\n- Code status is UNUSED or ACTIVE\n- Code has not expired\nExamples: \"LOYALTY15OFF\", \"VIP20\", \"WELCOME10\"\n", "example": "LOYALTY15OFF", "maxLength": 100, "type": "string" } }, "required": [ "customerId", "discountCode" ], "type": "object" }, "Customer": { "properties": { "availablePoints": { "format": "double", "type": "number" }, "availableStoreCredits": { "format": "double", "type": "number" }, "createAt": { "format": "date-time", "type": "string" }, "customerId": { "format": "int64", "type": "integer" }, "displayName": { "type": "string" }, "dob": { "format": "date", "type": "string" }, "email": { "type": "string" }, "emailBouncedOrFailed": { "type": "boolean" }, "emailSetting": { "type": "string" }, "enableEmail": { "type": "boolean" }, "enableEmailMarketing": { "type": "boolean" }, "enableSmsMarketing": { "type": "boolean" }, "firstName": { "type": "string" }, "id": { "format": "int64", "type": "integer" }, "isDeletedFromShopify": { "type": "boolean" }, "lastActivity": { "format": "date-time", "type": "string" }, "lastMonthlyReminderSentDate": { "format": "date-time", "type": "string" }, "lastName": { "type": "string" }, "lastRewardExpiryReminderSentDate": { "format": "date-time", "type": "string" }, "loyaltyProgramEnabled": { "type": "boolean" }, "ordersCount": { "format": "int32", "type": "integer" }, "pendingPoints": { "format": "double", "type": "number" }, "phone": { "type": "string" }, "redeemLimit": { "format": "int64", "type": "integer" }, "redeemLimitOnce": { "format": "int64", "type": "integer" }, "redeemedPoints": { "format": "double", "type": "number" }, "shop": { "type": "string" }, "skipReview": { "type": "boolean" }, "spentAmount": { "format": "double", "type": "number" }, "status": { "enum": [ "ACTIVE", "INACTIVE", "EXCLUDED", "EXCLUDED_BY_CUSTOMER" ], "type": "string" }, "storeCreditAccountId": { "type": "string" }, "tags": { "type": "string" }, "token": { "type": "string" }, "updatedSettings": { "type": "string" }, "vipAssignType": { "enum": [ "MANUAL", "AUTO_RENEWAL", "RENEWAL_ON_HIGHER_TIER" ], "type": "string" }, "vipTier": { "type": "string" }, "vipTierAmount": { "format": "double", "type": "number" }, "vipTierExpiredAt": { "format": "date-time", "type": "string" }, "vipTierId": { "format": "int64", "type": "integer" }, "vipTierSummary": { "type": "string" } }, "required": [ "availablePoints", "createAt", "customerId", "pendingPoints", "shop" ], "type": "object" }, "CustomerAddCreditsLoyaltyRequestVM": { "description": "Request containing customer ID/email, credits to add, and optional description", "properties": { "credits": { "format": "double", "type": "number" }, "customerEmail": { "type": "string" }, "customerId": { "format": "int64", "type": "integer" }, "earnRuleId": { "format": "int64", "type": "integer" }, "note": { "type": "string" } }, "type": "object" }, "CustomerAddPointsLoyaltyRequestVM": { "description": "Request containing customer ID/email, points to add, and optional description", "example": { "customerEmail": "customer@example.com", "note": "Compensation for delayed shipping - Order #1234", "points": 50.0 }, "properties": { "customerEmail": { "description": "Customer's email address. Alternative to customerId for identifying the customer.\nProvide either customerId OR customerEmail, not both.\nMust be a valid email address that exists in your Shopify store.\nEmail matching is case-insensitive.\nExample: customer@example.com\n", "example": "customer@example.com", "nullable": true, "type": "string" }, "customerId": { "description": "Shopify customer ID (numeric). Identifies which customer receives the points.\nProvide either customerId OR customerEmail, not both.\nCustomer must be enrolled in the loyalty program.\nExample: 67890\n", "example": 67890, "format": "int64", "nullable": true, "type": "integer" }, "earnRuleId": { "description": "Optional: ID of an earn rule to associate with this point addition.\nUsed for categorization and reporting purposes only.\nDoes not affect point calculation - points parameter takes precedence.\nHelps group similar types of point additions in reports.\nExample: 10\n", "example": 10, "format": "int64", "nullable": true, "type": "integer" }, "note": { "description": "Optional but strongly recommended: Description of why points are being added.\nThis note appears in the customer's transaction history and admin logs.\nBest practices:\n- Be specific about the reason\n- Include reference numbers (order ID, ticket ID, etc.)\n- Use consistent formatting for easier reporting\nExamples:\n- \"Birthday bonus - January 2025\"\n- \"Compensation for delayed shipping - Order #1234\"\n- \"Referral bonus from external campaign\"\n- \"Migration - transferred from old system\"\n- \"Manual adjustment per support ticket #567\"\n", "example": "Compensation for delayed shipping - Order #1234", "maxLength": 500, "nullable": true, "type": "string" }, "points": { "description": "Number of points to add to the customer's account. Must be a positive number.\nPoints are added to availablePoints immediately (not pending).\nDecimal values are supported for fractional points.\nExample: 50.0\n", "example": 50.0, "format": "double", "minimum": 0.01, "type": "number" } }, "required": [ "points" ], "type": "object" }, "CustomerBirthDateRequestVM": { "description": "Request containing customer ID and birth date", "example": { "customerId": 0, "dob": "2026-01-12", "status": "ACTIVE" }, "properties": { "customerId": { "description": "Unique identifier of the customer", "example": 0, "format": "int64", "type": "integer" }, "dob": { "description": "Customer date of birth", "example": "2026-01-12", "format": "date", "type": "string" }, "status": { "description": "Customer loyalty status", "enum": [ "ACTIVE", "INACTIVE", "EXCLUDED", "EXCLUDED_BY_CUSTOMER", "ACTIVE", "INACTIVE", "EXCLUDED", "EXCLUDED_BY_CUSTOMER" ], "type": "string" } }, "type": "object" }, "CustomerLoyaltyRequestVM": { "description": "Redemption request with customer ID/email, redeem rule ID, points to redeem", "example": { "customerId": 67890, "points": 100.0, "redeemRuleId": 5, "variantId": 12345678 }, "properties": { "customerEmail": { "description": "Customer's email address. Alternative to customerId for identifying the customer.\nProvide either customerId OR customerEmail, not both.\nMust be a valid email address that exists in your Shopify store.\nExample: customer@example.com\n", "example": "customer@example.com", "nullable": true, "type": "string" }, "customerId": { "description": "Shopify customer ID (numeric). Identifies which customer is redeeming points.\nProvide either customerId OR customerEmail, not both.\nExample: 67890\n", "example": 67890, "format": "int64", "nullable": true, "type": "integer" }, "points": { "description": "Number of points to redeem. Must be positive.\nIf not provided, uses the default points value from the redemption rule.\nCustomer must have at least this many available points.\nExample: 100.0\n", "example": 100.0, "format": "double", "nullable": true, "type": "number" }, "redeemRuleId": { "description": "ID of the redemption rule to use. Determines what reward the customer receives.\nUse GET /api/external/point-redeem-rules to get available redemption options.\nMust be an active redemption rule configured in your loyalty program.\nExample: 5\n", "example": 5, "format": "int64", "type": "integer" }, "variantId": { "description": "Shopify product variant ID. Required when redeeming for product-specific rewards (free product).\nNot required for discount codes or store credit rewards.\nMust be a valid variant ID from your Shopify catalog.\nExample: 12345678\n", "example": 12345678, "format": "int64", "nullable": true, "type": "integer" } }, "required": [ "redeemRuleId" ], "type": "object" }, "CustomerLoyaltyResponseVM": { "properties": { "achievableTierId": { "format": "int64", "type": "integer" }, "availablePoints": { "format": "double", "type": "number" }, "createAt": { "format": "date-time", "type": "string" }, "creditedPoints": { "format": "double", "type": "number" }, "currentVipTier": { "type": "string" }, "customerStatus": { "enum": [ "ACTIVE", "INACTIVE", "EXCLUDED", "EXCLUDED_BY_CUSTOMER" ], "type": "string" }, "dob": { "format": "date", "type": "string" }, "expiringPointsAmount": { "format": "double", "type": "number" }, "pendingPoints": { "format": "double", "type": "number" }, "pointsExpireAt": { "format": "date-time", "type": "string" }, "referralLink": { "type": "string" }, "referredCompleted": { "format": "int64", "type": "integer" }, "rewardedForCreatingAccount": { "type": "boolean" }, "rewardedForFacebook": { "type": "boolean" }, "rewardedForInstagram": { "type": "boolean" }, "rewardedForNewsLetter": { "type": "boolean" }, "rewardedForPinterest": { "type": "boolean" }, "rewardedForSharingOnFacebook": { "type": "boolean" }, "rewardedForSharingOnX": { "type": "boolean" }, "rewardedForSms": { "type": "boolean" }, "rewardedForTiktok": { "type": "boolean" }, "rewardedForTwitter": { "type": "boolean" }, "rewardedForYoutube": { "type": "boolean" }, "rewards": { "items": { "$ref": "#/components/schemas/CustomerReward" }, "type": "array" }, "spentAmount": { "format": "double", "type": "number" }, "storeCreditBalance": { "format": "double", "type": "number" }, "storeCreditCurrency": { "type": "string" }, "vipTierExpiredAt": { "format": "date-time", "type": "string" }, "vipTierSpentAmount": { "format": "double", "type": "number" } }, "type": "object" }, "CustomerReward": { "properties": { "amount": { "format": "double", "type": "number" }, "createAt": { "format": "date-time", "type": "string" }, "customerId": { "format": "int64", "type": "integer" }, "description": { "type": "string" }, "discountCode": { "type": "string" }, "discountCodeId": { "type": "string" }, "expireDate": { "format": "date-time", "type": "string" }, "id": { "format": "int64", "type": "integer" }, "lastExpiryReminderSentDate": { "format": "date-time", "type": "string" }, "orderId": { "format": "int64", "type": "integer" }, "orderName": { "type": "string" }, "pointRedeemRuleId": { "format": "int64", "type": "integer" }, "pointTransactionId": { "format": "int64", "type": "integer" }, "productData": { "type": "string" }, "rewardType": { "enum": [ "STORE_CREDIT", "DISCOUNT_CODE", "POINTS" ], "type": "string" }, "shop": { "type": "string" }, "status": { "enum": [ "USED", "UNUSED", "REFUNDED", "EXPIRED", "SUBSCRIPTION_ACTIVE", "CANCELED" ], "type": "string" }, "usageCount": { "format": "int64", "type": "integer" }, "usedAt": { "format": "date-time", "type": "string" }, "variantId": { "format": "int64", "type": "integer" } }, "required": [ "createAt", "customerId", "discountCode", "shop", "status" ], "type": "object" }, "Pageable": { "properties": { "page": { "format": "int32", "minimum": 0, "type": "integer" }, "size": { "format": "int32", "minimum": 1, "type": "integer" }, "sort": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "PendingPointsApprovalRequest": { "properties": { "customerId": { "format": "int64", "type": "integer" }, "transactionId": { "format": "int64", "type": "integer" } }, "type": "object" }, "PointEarnRuleDTO": { "properties": { "activityType": { "enum": [ "REGULAR", "REFERRAL", "VIP" ], "type": "string" }, "addAdditionalPhotoPoints": { "type": "boolean" }, "addAdditionalPoints": { "type": "boolean" }, "addAdditionalVideoPoints": { "type": "boolean" }, "additionalPhotoPoints": { "format": "double", "type": "number" }, "additionalPoints": { "format": "double", "type": "number" }, "additionalVideoPoints": { "format": "double", "type": "number" }, "allowedCustomerTags": { "type": "string" }, "allowedOrderTags": { "type": "string" }, "allowedProductTags": { "type": "string" }, "appliesOn": { "enum": [ "ONE_TIME", "SUBSCRIPTION", "BOTH" ], "type": "string" }, "applyOnImportedCustomer": { "type": "boolean" }, "autoApprovalDays": { "format": "int32", "type": "integer" }, "basePoints": { "format": "double", "type": "number" }, "collectionData": { "type": "string" }, "collectionId": { "format": "int64", "type": "integer" }, "createAt": { "format": "date-time", "type": "string" }, "customerFacingIconUrl": { "type": "string" }, "customerFacingLabel": { "type": "string" }, "customerNotification": { "type": "string" }, "disableForOnSellProduct": { "type": "boolean" }, "disablePointsForDiscountedProduct": { "type": "boolean" }, "earnLimit": { "format": "int32", "type": "integer" }, "earnType": { "enum": [ "STORE_CREDIT", "DISCOUNT_CODE", "POINTS" ], "type": "string" }, "eligibleForFirstOrder": { "type": "boolean" }, "enableBirthdayPromo": { "type": "boolean" }, "enableInterval": { "type": "boolean" }, "excludeCollections": { "type": "string" }, "excludeOrderTags": { "type": "string" }, "excludeProducts": { "type": "string" }, "excludeVariantIds": { "type": "string" }, "givePointsToGuestCustomers": { "type": "boolean" }, "historicPurchaseDuration": { "enum": [ "NONE", "ALL", "ONE_HOUR", "ONE_DAY", "ONE_MONTH", "THREE_MONTH", "ONE_YEAR" ], "type": "string" }, "id": { "format": "int64", "type": "integer" }, "includeShippingPoints": { "type": "boolean" }, "includeSubtotal": { "type": "boolean" }, "includeTax": { "type": "boolean" }, "manuallyApprovePoints": { "type": "boolean" }, "maximumPoints": { "format": "int32", "type": "integer" }, "minimumOrderValue": { "format": "double", "type": "number" }, "name": { "type": "string" }, "platformType": { "enum": [ "POS_ONLY", "ONLINE_STORE", "BOTH" ], "type": "string" }, "pointBasedOn": { "enum": [ "QUANTITY", "AMOUNT_SPEND", "FLAT_PURCHASE" ], "type": "string" }, "pointsProvided": { "format": "double", "type": "number" }, "productData": { "type": "string" }, "productId": { "format": "int64", "type": "integer" }, "promoPointsMultiplier": { "format": "double", "type": "number" }, "refundNotificationLabel": { "type": "string" }, "restrictCustomerTags": { "type": "string" }, "restrictProductTags": { "type": "string" }, "rewardAssignType": { "enum": [ "DYNAMIC", "FIXED" ], "type": "string" }, "rewardInterval": { "enum": [ "DAY", "WEEK", "MONTH", "YEAR", "LIFETIME" ], "type": "string" }, "rollBackPointsOnUnsubscribe": { "type": "boolean" }, "ruleEndDate": { "format": "date-time", "type": "string" }, "ruleStartDate": { "format": "date-time", "type": "string" }, "serial": { "format": "int32", "type": "integer" }, "shop": { "type": "string" }, "showReviewProductDetails": { "type": "boolean" }, "socialUrl": { "type": "string" }, "status": { "enum": [ "ACTIVE", "INACTIVE" ], "type": "string" }, "translations": { "type": "string" }, "triggeredCount": { "format": "int64", "type": "integer" }, "type": { "enum": [ "PURCHASE", "VISIT_SHOP", "REFERRAL", "CREATE_ACCOUNT", "FACEBOOK_PAGE_LIKE", "FOLLOW_TWITTER", "FOLLOW_INSTAGRAM", "BIRTHDAY", "LEAVE_REVIEW", "SUBSCRIBE_NEWSLETTER", "BUY_PRODUCT", "BUY_PRODUCT_FROM_COLLECTION", "LEAVE_REVIEW_STAMPED_IO", "LEAVE_REVIEW_LOOX_IO", "LEAVE_REVIEW_JUDGE_ME", "LEAVE_REVIEW_PRODUCT_REVIEWS", "SUBSCRIPTION", "YOUTUBE", "TIKTOK", "OKENDO", "HELPFULL_PRODUCT_REVIEWS", "RIVYO_PRODUCT_REVIEWS", "REVIEWS_IO", "QUANTITY_BASED_POINTS", "SUBSCRIBE_SMS", "VISIT_PINTEREST", "AIR_REVIEWS", "STATIC_EARN_RULE", "SHARE_ON_FACEBOOK", "SHARE_ON_X", "FIXED_REWARD" ], "type": "string" }, "updateAt": { "format": "date-time", "type": "string" }, "variantId": { "format": "int64", "type": "integer" }, "vipTierId": { "format": "int64", "type": "integer" } }, "required": [ "basePoints", "customerNotification", "includeShippingPoints", "includeSubtotal", "includeTax", "name", "status", "type" ], "type": "object" }, "PointRedeemRuleDTO": { "properties": { "allowedCountries": { "type": "string" }, "allowedCustomerTags": { "type": "string" }, "appliesOn": { "enum": [ "ONE_TIME", "SUBSCRIPTION", "BOTH" ], "type": "string" }, "applyDiscountOnce": { "type": "boolean" }, "applyToEachItem": { "type": "boolean" }, "collectionData": { "type": "string" }, "collectionId": { "format": "int64", "type": "integer" }, "combinedWithOrderDiscount": { "type": "boolean" }, "combinedWithProductDiscount": { "type": "boolean" }, "combinedWithShippingDiscount": { "type": "boolean" }, "createAt": { "format": "date-time", "type": "string" }, "customerFacingIconUrl": { "type": "string" }, "customerFacingLabel": { "type": "string" }, "discount": { "format": "double", "type": "number" }, "discountCodeForAllCustomer": { "type": "boolean" }, "discountCodeNodeId": { "type": "string" }, "discountPrefixText": { "type": "string" }, "discountType": { "enum": [ "PERCENTAGE", "FIXED" ], "type": "string" }, "earnRuleId": { "format": "int64", "type": "integer" }, "enableDiscountPrefix": { "type": "boolean" }, "enableInterval": { "type": "boolean" }, "enableMaximumPointsToRedeem": { "type": "boolean" }, "enableMinimumPointsToRedeem": { "type": "boolean" }, "enableNumberOfUsagesLimit": { "type": "boolean" }, "enablePOS": { "type": "boolean" }, "id": { "format": "int64", "type": "integer" }, "maximumPointsLabel": { "type": "string" }, "maximumShippingRate": { "format": "double", "type": "number" }, "minimumPointsLabel": { "type": "string" }, "minimumPurchaseAmount": { "format": "double", "type": "number" }, "name": { "type": "string" }, "numberOfUsagesLimit": { "format": "int32", "type": "integer" }, "pointsCost": { "format": "double", "type": "number" }, "productData": { "type": "string" }, "productId": { "format": "int64", "type": "integer" }, "quantity": { "format": "int32", "type": "integer" }, "redeemAllPoints": { "type": "boolean" }, "redeemLabel": { "type": "string" }, "redeemLimit": { "format": "int32", "type": "integer" }, "redeemPoints": { "format": "double", "type": "number" }, "referralType": { "enum": [ "EXISTING_CUSTOMER_REWARD", "NEW_CUSTOMER_REWARD", "VIP" ], "type": "string" }, "requiredMaximumPointsToRedeem": { "format": "double", "type": "number" }, "requiredMinimumPointsToRedeem": { "format": "double", "type": "number" }, "restrictCustomers": { "type": "string" }, "restrictCustomersWithTags": { "type": "string" }, "rewardInterval": { "enum": [ "DAY", "WEEK", "MONTH", "YEAR", "LIFETIME" ], "type": "string" }, "serial": { "format": "int32", "type": "integer" }, "shop": { "type": "string" }, "showInPosOnly": { "type": "boolean" }, "status": { "enum": [ "ACTIVE", "INACTIVE" ], "type": "string" }, "translations": { "type": "string" }, "triggeredCount": { "format": "int64", "type": "integer" }, "type": { "enum": [ "DISCOUNT_CODE", "FREE_PRODUCT", "FREE_SHIPPING", "PRODUCT_DISCOUNT", "COLLECTION_DISCOUNT", "BIRTHDAY_REWARD", "DYNAMIC_DISCOUNT", "STATIC_REDEEM_RULE", "STORE_CREDIT" ], "type": "string" }, "updateAt": { "format": "date-time", "type": "string" }, "variantId": { "format": "int64", "type": "integer" }, "vipTierId": { "format": "int64", "type": "integer" } }, "required": [ "discount", "discountType", "minimumPurchaseAmount", "name", "redeemPoints", "status", "type" ], "type": "object" }, "PointTransaction": { "properties": { "autoApprovalDays": { "format": "int32", "type": "integer" }, "contractId": { "type": "string" }, "createAt": { "format": "date-time", "type": "string" }, "customerId": { "format": "int64", "type": "integer" }, "displayName": { "type": "string" }, "earnRuleId": { "format": "int64", "type": "integer" }, "earnRuleName": { "type": "string" }, "id": { "format": "int64", "type": "integer" }, "imported": { "type": "boolean" }, "note": { "type": "string" }, "orderFinancialStatus": { "type": "string" }, "orderFulfillmentStatus": { "type": "string" }, "orderId": { "format": "int64", "type": "integer" }, "orderLineItemId": { "format": "int64", "type": "integer" }, "orderName": { "type": "string" }, "pointType": { "enum": [ "DEBIT", "CREDIT" ], "type": "string" }, "points": { "format": "double", "type": "number" }, "reason": { "type": "string" }, "redeemRuleName": { "type": "string" }, "redeemRuleRuleId": { "format": "int64", "type": "integer" }, "reviewReference": { "type": "string" }, "rewardType": { "enum": [ "STORE_CREDIT", "DISCOUNT_CODE", "POINTS" ], "type": "string" }, "shop": { "type": "string" }, "spentAmount": { "format": "double", "type": "number" }, "status": { "enum": [ "APPROVED", "PENDING", "REJECTED" ], "type": "string" }, "transactionRule": { "enum": [ "ADJUSTMENT", "EARN_RULE", "REDEEM_RULE", "REFERRAL" ], "type": "string" } }, "required": [ "customerId", "pointType", "points" ], "type": "object" }, "TopCustomerVM": { "properties": { "activitiesCompleted": { "format": "int64", "type": "integer" }, "customerId": { "format": "int64", "type": "integer" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "pointsEarned": { "format": "double", "type": "number" } }, "type": "object" }, "UpdateDiscountCodeStatusRequestVM": { "description": "Request containing customer ID/email, discount code, and new status", "properties": { "customerEmail": { "type": "string" }, "customerId": { "format": "int64", "type": "integer" }, "discountCode": { "type": "string" }, "status": { "type": "string" } }, "required": [ "discountCode", "status" ], "type": "object" }, "UpdateDiscountRequest": { "description": "Request containing customer ID, discount code, and new status", "example": { "customerId": 67890, "discountCode": "LOYALTY15OFF", "status": "USED" }, "properties": { "customerId": { "description": "Shopify customer ID (numeric). Identifies which customer owns the discount code.\nUsed to verify the discount code belongs to this customer before updating.\nExample: 67890\n", "example": 67890, "format": "int64", "type": "integer" }, "discountCode": { "description": "The discount code to update. Case-insensitive.\nMust be a valid loyalty discount code that belongs to the specified customer.\nExamples: \"LOYALTY15OFF\", \"VIP20\", \"WELCOME10\"\n", "example": "LOYALTY15OFF", "maxLength": 100, "type": "string" }, "status": { "description": "New status for the discount code. Valid values:\n- USED: Mark code as used after checkout (most common)\n- SUBSCRIPTION_ACTIVE: Mark code as active for subscription renewals\n- UNUSED: Reset code to unused state (use carefully)\n- EXPIRED: Manually expire a code\n\nStatus transitions:\n- UNUSED \u2192 USED: Normal checkout flow\n- UNUSED \u2192 SUBSCRIPTION_ACTIVE: Subscription created\n- SUBSCRIPTION_ACTIVE \u2192 USED: Subscription ended\n- Any \u2192 EXPIRED: Manual expiration\n\nNote: Cannot mark already USED codes as USED again.\n", "enum": [ "USED", "UNUSED", "REFUNDED", "EXPIRED", "SUBSCRIPTION_ACTIVE", "CANCELED", "USED", "UNUSED", "SUBSCRIPTION_ACTIVE", "EXPIRED" ], "example": "USED", "type": "string" } }, "required": [ "customerId", "discountCode", "status" ], "type": "object" }, "WidgetLabelDTO": { "properties": { "acquirePointsLabel": { "type": "string" }, "acquirePointsLoggedOutText": { "type": "string" }, "acquireStoreCreditLabel": { "type": "string" }, "alreadyHaveAnAccountLabel": { "type": "string" }, "approvedStatusLabel": { "type": "string" }, "authenticationLabel": { "type": "string" }, "availablePoints": { "type": "string" }, "birthdayActionLabel": { "type": "string" }, "birthdayDayPlaceholderLabel": { "type": "string" }, "birthdayMonthPlaceholderLabel": { "type": "string" }, "birthdayProfileLabel": { "type": "string" }, "birthdayTitleLabel": { "type": "string" }, "birthdayUpdatedToastLabel": { "type": "string" }, "birthdayYearPlaceholderLabel": { "type": "string" }, "cartWidgetAvailableBalanceLabel": { "type": "string" }, "cartWidgetLoginLinkLabel": { "type": "string" }, "cartWidgetLoginMessageLabel": { "type": "string" }, "cartWidgetRewardsButtonLabel": { "type": "string" }, "checkThankYouAcquiredPointsHeadingLabel": { "type": "string" }, "checkoutAcquiredPointsLabel": { "type": "string" }, "checkoutAvailableRewardsLabel": { "type": "string" }, "checkoutDiscountCodeApplyButtonLabel": { "type": "string" }, "checkoutEmptyRewardsLabel": { "type": "string" }, "checkoutPendingPointsLabel": { "type": "string" }, "checkoutRedeemLabel": { "type": "string" }, "checkoutRedeemLoginDescription": { "type": "string" }, "checkoutRedeemLoginLabel": { "type": "string" }, "checkoutSelectRedeemRuleDropdownLabel": { "type": "string" }, "checkoutToggleAvailableRewardsButtonLabel": { "type": "string" }, "checkoutToggleRedeemButtonLabel": { "type": "string" }, "checkoutTotalAcquirePoints": { "type": "string" }, "checkoutTotalAcquirePointsDescription": { "type": "string" }, "checkoutTotalStoreCreditAcquirePoints": { "type": "string" }, "checkoutViewMoreDiscountCodeButtonLabel": { "type": "string" }, "chooseAnOptionLabel": { "type": "string" }, "claimGiftHeaderText": { "type": "string" }, "claimReferralEmailFieldHintText": { "type": "string" }, "claimReferralEmailFieldText": { "type": "string" }, "claimReferralGiftButtonText": { "type": "string" }, "claimReferralGiftDescriptionText": { "type": "string" }, "claimRewardButtonLabel": { "type": "string" }, "claimedStatusLabel": { "type": "string" }, "createAccountLabel": { "type": "string" }, "creditRewardDetailsHelpLabel": { "type": "string" }, "currentVipTierBadgeLabel": { "type": "string" }, "currentVipTierText": { "type": "string" }, "customerHistoryDescriptionLabel": { "type": "string" }, "customerHistoryLabel": { "type": "string" }, "customerReferralClaimedStatus": { "type": "string" }, "customerReferralPendingStatus": { "type": "string" }, "customerReferralRecurringStatus": { "type": "string" }, "dailyLimitExceedText": { "type": "string" }, "default": { "type": "boolean" }, "discountAppliedAtCheckoutMessage": { "type": "string" }, "discountAppliedLabel": { "type": "string" }, "discountCodeLabel": { "type": "string" }, "dynamicPointsHelpText": { "type": "string" }, "dynamicPointsLabel": { "type": "string" }, "emailValidationLabel": { "type": "string" }, "enrollLoyaltyProgramActionLabel": { "type": "string" }, "enrollLoyaltyProgramDescription": { "type": "string" }, "enrollLoyaltyProgramTitle": { "type": "string" }, "enrolledSuccessMessage": { "type": "string" }, "excludeCustomerLabel": { "type": "string" }, "exploreLabel": { "type": "string" }, "faq": { "type": "string" }, "freeProductRewardAddToCart": { "type": "string" }, "freeProductRewardAddedSuccessMessage": { "type": "string" }, "historyActivityDetails": { "type": "string" }, "historyDate": { "type": "string" }, "historyPointsAdjustment": { "type": "string" }, "historyStatus": { "type": "string" }, "homeGreetings": { "type": "string" }, "homeSignup": { "type": "string" }, "howItWorksStep1Count": { "type": "string" }, "howItWorksStep1Description": { "type": "string" }, "howItWorksStep1Title": { "type": "string" }, "howItWorksStep2Count": { "type": "string" }, "howItWorksStep2Description": { "type": "string" }, "howItWorksStep2Title": { "type": "string" }, "howItWorksStep3Count": { "type": "string" }, "howItWorksStep3Description": { "type": "string" }, "howItWorksStep3Title": { "type": "string" }, "howItWorksTitle": { "type": "string" }, "howItWorksTitleDescription": { "type": "string" }, "id": { "format": "int64", "type": "integer" }, "includeCustomerLabel": { "type": "string" }, "isDefault": { "type": "boolean" }, "labelsJson": { "type": "string" }, "locale": { "type": "string" }, "loyaltyOptOutActiveLabel": { "type": "string" }, "loyaltyOptOutLabel": { "type": "string" }, "loyaltyOptOutSettingsLabel": { "type": "string" }, "loyaltyOptoutActive": { "type": "string" }, "loyaltyOptoutInactive": { "type": "string" }, "loyaltyPageHeroV2AuthenticatedHeading": { "type": "string" }, "loyaltyPageHeroV2Heading": { "type": "string" }, "loyaltyPageHeroV2SubHeading": { "type": "string" }, "loyaltyPageMetaDescription": { "type": "string" }, "loyaltyPageMetaTitle": { "type": "string" }, "loyaltyStatusLabel": { "type": "string" }, "manageLoyaltyButtonLabel": { "type": "string" }, "membershipRewardTitleLabel": { "type": "string" }, "minimumAmountSpentForRedeemText": { "type": "string" }, "minimumOrderCountForRedeemText": { "type": "string" }, "minimumPointsForRedeemText": { "type": "string" }, "minimumRedeemRequiredPointsLabel": { "type": "string" }, "noCustomerHistoryDescriptionLabel": { "type": "string" }, "noCustomerHistoryLabel": { "type": "string" }, "noEarnRulesLabel": { "type": "string" }, "noRedeemRulesLabel": { "type": "string" }, "noRefferralAvailableText": { "type": "string" }, "notEligibleLabel": { "type": "string" }, "noteHeadingLabel": { "type": "string" }, "otherRulesRedirectActionLabel": { "type": "string" }, "pendingStatusLabel": { "type": "string" }, "perTransactionLimitExceedText": { "type": "string" }, "pointExpirationDateLabel": { "type": "string" }, "pointsBalanceLabel": { "type": "string" }, "popupAvailableRewardsContentText": { "type": "string" }, "popupAvailableRewardsHeadingText": { "type": "string" }, "popupCardActionText": { "type": "string" }, "popupCardContentText": { "type": "string" }, "popupCardHeadingText": { "type": "string" }, "popupCommunityContentText": { "type": "string" }, "popupCommunityHeadingText": { "type": "string" }, "popupCopiedDiscount": { "type": "string" }, "popupCopyDiscount": { "type": "string" }, "popupDiscountCodeGenerated": { "type": "string" }, "popupEarnPointDescriptionText": { "type": "string" }, "popupEarnRewardsHeadingText": { "type": "string" }, "popupEarnTilesText": { "type": "string" }, "popupFAQAskedQuestionHeadingText": { "type": "string" }, "popupFAQHeadingText": { "type": "string" }, "popupRedeemRewardsHeadingText": { "type": "string" }, "popupRedeemTilesText": { "type": "string" }, "popupReferralContentText": { "type": "string" }, "popupReferralTitleText": { "type": "string" }, "popupRemainingPointsHeadingText": { "type": "string" }, "popupRewardPointContentText": { "type": "string" }, "popupRewardPointTitleText": { "type": "string" }, "popupRewardsDetailsHeadingText": { "type": "string" }, "popupWelcomeText": { "type": "string" }, "programUpdateMessage": { "type": "string" }, "recurringStatusLabel": { "type": "string" }, "redeemActionLabel": { "type": "string" }, "redeemLimitExceedText": { "type": "string" }, "referButtonLabel": { "type": "string" }, "referYourFriendContentText": { "type": "string" }, "referYourFriendTitleText": { "type": "string" }, "referralCompletedText": { "type": "string" }, "referralCustomerGetText": { "type": "string" }, "referralFriendGetText": { "type": "string" }, "referralLinkSentDescription": { "type": "string" }, "referralLinkSentLabel": { "type": "string" }, "referredByText": { "type": "string" }, "referredEmailHeadingLabel": { "type": "string" }, "rejectedStatusLabel": { "type": "string" }, "reviewRuleRedirectActionLabel": { "type": "string" }, "rewardDetailsButtonLabel": { "type": "string" }, "rewardDetailsHelpLabel": { "type": "string" }, "rewardDetailsTitleLabel": { "type": "string" }, "rewardsDetailsExpireDate": { "type": "string" }, "rewardsExpirationLabel": { "type": "string" }, "sendEmailButtonText": { "type": "string" }, "sendEmailHeadingText": { "type": "string" }, "sendRefferralLink": { "type": "string" }, "sentDiscountCodeToEmailText": { "type": "string" }, "shareReferralEmailFieldText": { "type": "string" }, "shareReferralLinkLabel": { "type": "string" }, "shareSocialMediaLabel": { "type": "string" }, "shop": { "type": "string" }, "socialMediaActionLabel": { "type": "string" }, "statusHeadingLabel": { "type": "string" }, "storeCreditApplyGuideLabel": { "type": "string" }, "storeCreditBalanceLabel": { "type": "string" }, "storeOnSaleForRedeemText": { "type": "string" }, "subscribeRuleRedirectActionLabel": { "type": "string" }, "toastErrorMsg": { "type": "string" }, "totalAcquiredPointsLabel": { "type": "string" }, "totalAcquiredStoreCreditsLabel": { "type": "string" }, "transactionHistoryPaginationLabel": { "type": "string" }, "vipAchievableTierLabel": { "type": "string" }, "vipCurrentTierLabel": { "type": "string" }, "vipEarnPointLabel": { "type": "string" }, "vipRewardLabel": { "type": "string" }, "vipSpentAmountLabel": { "type": "string" }, "vipStatusLabel": { "type": "string" }, "vipTierBenefits": { "type": "string" }, "vipTierDetailsText": { "type": "string" }, "vipTierTitleLabel": { "type": "string" }, "widgetCopiedLabel": { "type": "string" }, "widgetDateTimeFormat": { "type": "string" }, "widgetTitle": { "type": "string" }, "yourReferralsHeadingLabel": { "type": "string" } }, "required": [ "locale" ], "type": "object" } } }, "info": { "description": "", "title": "Admin APIs" }, "openapi": "3.0.1", "paths": { "/api/external/add-credits": { "post": { "operationId": "externalAddCredits", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddCreditsLoyaltyRequestVM" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyResponseVM" } } }, "description": "Store credits successfully added to customer account" }, "400": { "description": "Invalid request - Invalid customer or credit amount" }, "401": { "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Add store credits to customer account", "tags": [ "Points & Earn Rules" ] } }, "/api/external/add-points": { "post": { "operationId": "externalAddPoints", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddPointsLoyaltyRequestVM" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "availablePoints": 350.0, "creditedPoints": 600.0, "currentVipTier": "Gold", "customerStatus": "ACTIVE", "pendingPoints": 0.0, "rewards": [], "spentAmount": 1250.99, "storeCreditBalance": 0.0 }, "schema": { "$ref": "#/components/schemas/CustomerLoyaltyResponseVM" } } }, "description": "Points successfully added to customer account" }, "400": { "content": { "application/json": { "schema": { "example": { "details": "Points must be a positive number", "error": "Invalid request" }, "type": "string" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "example": { "error": "Invalid API key" }, "type": "string" } } }, "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Add points to customer account", "tags": [ "Points & Earn Rules" ] } }, "/api/external/approve-pending-transactions": { "put": { "operationId": "approvePendingTransaction", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Set to true to approve all pending transactions (ignores pendingPointsApprovalList)", "in": "query", "name": "approveAllPendingTransactions", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "List of specific pending transactions to approve (ignored if approveAllPendingTransactions=true)", "items": { "$ref": "#/components/schemas/PendingPointsApprovalRequest" }, "type": "array" } } } }, "responses": { "204": { "description": "Approval process started successfully (asynchronous operation). Points will be added to customer accounts within a few seconds." }, "400": { "content": { "application/json": { "schema": { "example": { "details": "Must provide either approveAllPendingTransactions=true or a list of pending transactions to approve", "error": "Invalid request" }, "type": "string" } } }, "description": "Invalid request - Must provide either approveAllPendingTransactions=true OR a valid pendingPointsApprovalList" }, "401": { "content": { "application/json": { "schema": { "example": { "error": "Invalid API key" }, "type": "string" } } }, "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Approve pending point transactions", "tags": [ "Points & Earn Rules" ] } }, "/api/external/check-discount": { "put": { "operationId": "checkRewards", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckDiscountRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "createAt": "2025-01-15T10:30:00Z", "customerId": 67890, "discountCode": "LOYALTY15OFF", "discountType": "PERCENTAGE", "discountValue": 15.0, "expiryDate": "2025-06-30T23:59:59Z", "id": 12345, "minimumPurchaseAmount": 50.0, "pointsRedeemed": 100.0, "shopifyDiscountCodeId": "gid://shopify/DiscountCode/123", "status": "UNUSED" }, "schema": { "$ref": "#/components/schemas/CustomerReward" } } }, "description": "Discount code is valid and reward details returned" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Discount code already used", "status": "USED", "usedAt": "2025-01-20T14:30:00Z" }, "type": "string" } } }, "description": "Discount code not valid" }, "401": { "content": { "application/json": { "schema": { "example": { "error": "Invalid API key" }, "type": "string" } } }, "description": "Unauthorized - Invalid or missing X-API-Key" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Discount code not found for the specified customer" }, "type": "string" } } }, "description": "Discount code not found for this customer" } }, "security": [ { "X-API-Key": [] } ], "summary": "Check discount code validity", "tags": [ "Redemptions & Discount Codes" ] } }, "/api/external/customer-loyalty": { "get": { "operationId": "externalGetCustomerLoyalty", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Shopify customer ID (optional if customerEmail provided)", "in": "query", "name": "customerId", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Customer email address (optional if customerId provided)", "in": "query", "name": "customerEmail", "required": false, "schema": { "type": "string" } }, { "description": "Filter rewards by status (comma-separated: ACTIVE, USED, UNUSED)", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "achievableTierId": 2, "availablePoints": 250.0, "createAt": "2024-01-15T10:00:00Z", "creditedPoints": 500.0, "currentVipTier": "Gold", "customerStatus": "ACTIVE", "dob": "1990-05-15", "pendingPoints": 50.0, "referralLink": "https://yourstore.com/r/abc123", "referredCompleted": 3, "rewardedForCreatingAccount": true, "rewardedForFacebook": true, "rewardedForInstagram": false, "rewardedForNewsLetter": true, "rewardedForPinterest": false, "rewardedForSharingOnFacebook": false, "rewardedForSharingOnX": false, "rewardedForSms": false, "rewardedForTiktok": false, "rewardedForTwitter": false, "rewardedForYoutube": false, "rewards": [ { "discountCode": "LOYALTY10OFF", "discountType": "PERCENTAGE", "discountValue": 10.0, "expiryDate": "2025-06-30T23:59:59Z", "id": 12345, "pointsRedeemed": 100.0, "status": "UNUSED" } ], "spentAmount": 1250.99, "storeCreditBalance": 25.0, "vipTierExpiredAt": "2025-12-31T23:59:59Z" }, "schema": { "$ref": "#/components/schemas/CustomerLoyaltyResponseVM" } } }, "description": "Successfully retrieved customer loyalty details" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Either customerId or customerEmail is required" }, "type": "string" } } }, "description": "Bad request - Neither customerId nor customerEmail provided, or invalid status parameter" }, "401": { "content": { "application/json": { "schema": { "example": { "error": "Invalid API key" }, "type": "string" } } }, "description": "Unauthorized - Invalid or missing X-API-Key" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Customer not found" }, "type": "string" } } }, "description": "Customer not found - No customer exists with the provided ID or email" } }, "security": [ { "X-API-Key": [] } ], "summary": "Get customer loyalty details", "tags": [ "Customer Enrollment & Profile" ] } }, "/api/external/enroll-customer": { "post": { "operationId": "enrollCustomer", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Shopify customer ID to enroll in loyalty program", "in": "query", "name": "customer_id", "required": true, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "message": "Customer added successfully" }, "type": "string" } } }, "description": "Customer successfully enrolled in loyalty program" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Customer ID is required" }, "type": "string" } } }, "description": "Invalid request - Missing or invalid customer ID. Common causes: customer_id parameter missing, customer_id is not a valid number, or customer doesn't exist in Shopify." }, "401": { "content": { "application/json": { "schema": { "example": { "error": "Invalid API key" }, "type": "string" } } }, "description": "Unauthorized - Invalid or missing X-API-Key. Verify your API key is correct and included in the X-API-Key header." } }, "security": [ { "X-API-Key": [] } ], "summary": "Enroll customer in loyalty program", "tags": [ "Customer Enrollment & Profile" ] } }, "/api/external/point-earn-rules": { "get": { "operationId": "getAllPointEarnRules", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Include inactive rules in response (default: false)", "in": "query", "name": "includeInactive", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PointEarnRuleDTO" } } }, "description": "Successfully retrieved point earning rules" }, "401": { "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Get all point earning rules", "tags": [ "Points & Earn Rules" ] } }, "/api/external/point-redeem-rules": { "get": { "operationId": "getAllPointRedeemRules", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PointRedeemRuleDTO" } } }, "description": "Successfully retrieved point redemption rules" }, "401": { "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Get all point redemption rules", "tags": [ "Redemptions & Discount Codes" ] } }, "/api/external/point-transaction-history/{customer_id}": { "get": { "operationId": "getAllPointTransactionHistoryByCustomer", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Shopify customer ID to retrieve transaction history for", "in": "path", "name": "customer_id", "required": true, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PointTransaction" } } }, "description": "Successfully retrieved point transaction history" }, "401": { "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Get customer point transaction history", "tags": [ "Points & Earn Rules" ] } }, "/api/external/redeem-points": { "post": { "operationId": "externalRedeemPoints", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyRequestVM" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "availablePoints": 150.0, "creditedPoints": 500.0, "currentVipTier": "Gold", "customerStatus": "ACTIVE", "pendingPoints": 0.0, "rewards": [ { "createAt": "2025-01-29T10:30:00Z", "discountCode": "LOYALTY15OFF", "discountType": "PERCENTAGE", "discountValue": 15.0, "expiryDate": "2025-06-30T23:59:59Z", "id": 12346, "pointsRedeemed": 100.0, "status": "UNUSED" } ], "spentAmount": 1250.99, "storeCreditBalance": 0.0 }, "schema": { "$ref": "#/components/schemas/CustomerLoyaltyResponseVM" } } }, "description": "Points successfully redeemed and reward generated" }, "400": { "content": { "application/json": { "schema": { "example": { "details": "Customer has 50 points but needs 100 points for this redemption", "error": "Insufficient points" }, "type": "string" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "example": { "error": "Invalid API key" }, "type": "string" } } }, "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Redeem customer points for rewards", "tags": [ "Redemptions & Discount Codes" ] } }, "/api/external/remove-points": { "post": { "operationId": "externalRemovePoints", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddPointsLoyaltyRequestVM" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyResponseVM" } } }, "description": "Points successfully removed from customer account" }, "400": { "content": { "application/json": {} }, "description": "Invalid request \u2014 missing customer info or points" }, "401": { "content": { "application/json": {} }, "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Remove points from customer account", "tags": [ "Points & Earn Rules" ] } }, "/api/external/top-customers": { "get": { "operationId": "top10CustomerEarnedAndPoints", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Pagination parameters (page number, size, sort)", "in": "query", "name": "pageable", "required": true, "schema": { "$ref": "#/components/schemas/Pageable" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopCustomerVM" } } }, "description": "Successfully retrieved top customers with pagination headers", "headers": { "Link": { "description": "Pagination links for navigating results", "schema": { "type": "string" }, "style": "simple" }, "X-Total-Count": { "description": "Total number of customers", "schema": { "type": "integer" }, "style": "simple" } } }, "401": { "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Get top customers by points earned", "tags": [ "Points & Earn Rules" ] } }, "/api/external/update-customer-birth-date": { "put": { "operationId": "addCustomerBirthDate", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBirthDateRequestVM" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } }, "description": "Customer birth date successfully updated" }, "400": { "description": "Invalid request - Invalid date format or customer not found" }, "401": { "description": "Unauthorized - Invalid or missing X-API-Key" }, "500": { "description": "Internal server error during update" } }, "security": [ { "X-API-Key": [] } ], "summary": "Update customer birth date", "tags": [ "Customer Enrollment & Profile" ] } }, "/api/external/update-discount": { "put": { "operationId": "updateDiscount", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDiscountRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "createAt": "2025-01-15T10:30:00Z", "customerId": 67890, "discountCode": "LOYALTY15OFF", "discountType": "PERCENTAGE", "discountValue": 15.0, "expiryDate": "2025-06-30T23:59:59Z", "id": 12345, "pointsRedeemed": 100.0, "status": "USED", "usedAt": "2025-01-29T10:45:00Z" }, "schema": { "$ref": "#/components/schemas/CustomerReward" } } }, "description": "Discount code status successfully updated" }, "400": { "content": { "application/json": { "schema": { "example": { "currentStatus": "USED", "error": "Discount code already marked as used", "usedAt": "2025-01-20T14:30:00Z" }, "type": "string" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "example": { "error": "Invalid API key" }, "type": "string" } } }, "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Update discount code status", "tags": [ "Redemptions & Discount Codes" ] } }, "/api/external/update-discount-code-status": { "put": { "operationId": "externalMarkDiscountCodeAsUsed", "parameters": [ { "description": "API key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDiscountCodeStatusRequestVM" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyResponseVM" } } }, "description": "Discount code status updated and customer loyalty details returned" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized - Invalid or missing X-API-Key" } }, "security": [ { "X-API-Key": [] } ], "summary": "Update discount code status (legacy endpoint)", "tags": [ "Redemptions & Discount Codes" ] } }, "/api/external/widget-labels": { "get": { "operationId": "getWidgetLabels", "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "*/*": { "schema": { "items": { "$ref": "#/components/schemas/WidgetLabelDTO" }, "type": "array" } } }, "description": "OK" } }, "security": [ { "X-API-Key": [] } ], "summary": "List storefront widget label translations", "tags": [ "Storefront Widgets & Labels" ] } } }, "servers": [ { "url": "https://loyalty-admin.appstle.com" } ], "tags": [ { "description": "Admin APIs for enrolling customers into the loyalty program, retrieving customer loyalty details, and updating profile information such as birth date.", "name": "Customer Enrollment & Profile" }, { "description": "Admin APIs for managing customer point balances, transaction history, point earning rules, top customers leaderboard, and approving pending transactions.", "name": "Points & Earn Rules" }, { "description": "Admin APIs for redeeming customer points, managing redemption rules, and validating or updating discount codes generated through loyalty redemptions.", "name": "Redemptions & Discount Codes" }, { "description": "Admin APIs for retrieving storefront widget label translations consumed by the loyalty widget on the merchant's storefront.", "name": "Storefront Widgets & Labels" } ] }