{"openapi":"3.0.4","info":{"title":"Dotdigital Loyalty","description":"Manage loyalty program members, rewards, and rules. Use this API to retrieve\nmember details, points history, redemption history, and tier progress; list\navailable rewards and generate coupon codes; and list reward rules and register\nsocial media engagement events for a customer.","version":"v1.0.1"},"externalDocs":{"description":"Learn more about Dotdigital Loyalty APIs","url":"https://developer-loyalty.dotdigital.com/"},"servers":[{"url":"https://{region}-api.dotdigital.com","variables":{"region":{"description":"The Dotdigital region id your account belongs to","enum":["r1","r2","r3"],"default":"r1"}}}],"security":[{"basicAuth":[]}],"paths":{"/loyalty/v1/members":{"get":{"tags":["Members"],"summary":"Get loyalty members","description":"Retrieves all the loyalty members and their loyalty details.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","description":"The members details.","items":{"$ref":"#/components/schemas/MemberDetails"}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/loyalty/v1/members/{shopifyId}":{"get":{"tags":["Members"],"summary":"Get member loyalty data","description":"Retrieves all the loyalty details for the specified Shopify member.","parameters":[{"name":"shopifyId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/loyalty/v1/members/{shopifyId}/points-history":{"get":{"tags":["Members"],"summary":"Get a members reward point history","description":"Gets a members complete reward point history, so whenever a event has occurred that has affected their rewards point balance.","parameters":[{"name":"shopifyId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","description":"Members point history.","items":{"$ref":"#/components/schemas/MemberPointsHistoryEntry"}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/loyalty/v1/members/{shopifyId}/redemption-history":{"get":{"tags":["Members"],"summary":"Get a members reward redemption history","description":"Gets a members complete reward redemption history, a entry for each redemption of reward points they have claimed.","parameters":[{"name":"shopifyId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","description":"Members redemption history.","items":{"$ref":"#/components/schemas/MemberRedemptionHistoryEntry"}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/loyalty/v1/members/{shopifyId}/tier-progress":{"get":{"tags":["Members"],"summary":"Get a members progress towards the next tier","description":"Gets a members current progress towards the next reward tier.","parameters":[{"name":"shopifyId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberTierProgress"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/loyalty/v1/rewards/{rewardId}/coupon-code":{"post":{"tags":["Rewards"],"summary":"Creates a coupon code","description":"Creates a coupon code for a specific reward and customer.","parameters":[{"name":"rewardId","in":"path","description":"The unqiue reward id you want to issue a coupon for.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCouponCodeRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string","description":"The coupon code","example":"ABC12345"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/loyalty/v1/rewards":{"get":{"tags":["Rewards"],"summary":"List rewards","description":"Lists all the rewards available in your loyalty program.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RewardDetails"}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/loyalty/v1/rules":{"get":{"tags":["Rules"],"summary":"List rules","description":"Lists all the reward rules in your loyalty program.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RuleDetails"}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/loyalty/v1/rules/social-media-engagement/{ruleId}":{"post":{"tags":["Rules"],"summary":"Register social media engagment","description":"Register that a customer has engaged with social media and apply the reward rule specified.","parameters":[{"name":"ruleId","in":"path","description":"The reward rules id you want to apply to the customer.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSocialMediaEngagementRequest"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}}},"components":{"schemas":{"CreateCouponCodeRequest":{"required":["customerId"],"type":"object","properties":{"customerId":{"type":"integer","description":"Shopify customer id","format":"int64","example":3455522443}},"additionalProperties":false},"CreateSocialMediaEngagementRequest":{"required":["customerId"],"type":"object","properties":{"customerId":{"type":"integer","description":"The Shopify customer id you want to record the social media engagement for.","format":"int64","example":34865867949}},"additionalProperties":false},"MemberActivityType":{"type":"string","enum":["PointsManuallyAdjusted","PointsEarnedForOrder","PointsEarnedForSignUp","PointsEarnedForBirthday","PointsEarnedForAnniversary","PointsEarnedForSocialEngagement","CouponCreated","PointsExpired","PointsForRefund","OrderPlaced"]},"MemberDetails":{"required":["birthdayDate","currentTier","eligibleRewards","eligibleRules","email","emailMarketingConsentState","firstName","id","joinedDate","lastActivityDate","lastName","pointsBalance","pointsExpirationDate","smsMarketingConsentState","telephoneNumber"],"type":"object","properties":{"id":{"type":"integer","description":"Shopify id","format":"int64","example":12345},"firstName":{"type":"string","description":"Members first name","nullable":true,"example":"Some"},"lastName":{"type":"string","description":"Members last name","nullable":true,"example":"Member"},"email":{"type":"string","description":"Members email address","format":"email","nullable":true},"telephoneNumber":{"pattern":"^\\+[1-9]\\d{10,14}$","type":"string","description":"Members mobile phone number","nullable":true,"example":"+447123123123"},"birthdayDate":{"type":"string","description":"Members DOB","format":"date","nullable":true},"lastActivityDate":{"type":"string","description":"The date and time the members was last active in UTC time.","format":"date-time"},"pointsExpirationDate":{"type":"string","description":"The date and time the rewards points expire in UTC time.","format":"date-time","nullable":true},"joinedDate":{"type":"string","description":"The date and time that the member joined the rewards program in UTC time.","format":"date-time"},"pointsBalance":{"minimum":0,"type":"integer","description":"The members current reward points balance.","format":"int32"},"emailMarketingConsentState":{"type":"string","description":"The marketing consent state for emails.","example":"Subscribed","enum":["Not subscribed","Pending","Redacted","Subscribed","Unsubscribed"]},"smsMarketingConsentState":{"type":"string","description":"The marketing consent state for SMS/MMS/RCS.","example":"Unsubscribed","enum":["Not subscribed","Pending","Redacted","Subscribed","Unsubscribed"]},"eligibleRewards":{"type":"array","description":"Any rewards the member is currently eligible for.","nullable":true,"items":{"$ref":"#/components/schemas/MemberRewardDetails"}},"eligibleRules":{"type":"array","description":"Any member rules the member is currently eligible for.","nullable":true,"items":{"$ref":"#/components/schemas/MemberRuleDetails"}},"currentTier":{"allOf":[{"$ref":"#/components/schemas/TierDetails"},{"description":"The members current reward tier."}]}},"additionalProperties":false},"MemberPointsHistoryEntry":{"required":["entryDate","entryType","id","impactOnPoints","pointsBalance"],"type":"object","properties":{"id":{"type":"string","description":"The unique id for the record.","format":"uuid"},"entryType":{"allOf":[{"description":"The type of points entry.","example":"PointsEarnedForOrder"},{"$ref":"#/components/schemas/MemberActivityType"}]},"impactOnPoints":{"type":"integer","description":"The change in reward points.","format":"int32","example":617},"pointsBalance":{"type":"integer","description":"The points balance after the entry was applied.","format":"int32","example":627},"entryDate":{"type":"string","description":"The date and time the points entry occurred in UTC.","format":"date-time"}},"additionalProperties":false},"MemberRedemptionHistoryEntry":{"required":["cost","entryDate","entryType","id","metadata","name"],"type":"object","properties":{"id":{"type":"string","description":"The unique id for the record.","format":"uuid"},"cost":{"type":"integer","description":"The cost in reward points for the reward.","format":"int32","example":50},"entryType":{"allOf":[{"description":"The type reward."},{"$ref":"#/components/schemas/RewardType"}]},"name":{"type":"string","description":"The name of the reward.","nullable":true,"example":"Free P&P"},"entryDate":{"type":"string","description":"The date and time of the redemption in UTC.","format":"date-time"},"metadata":{"type":"object","description":"Any addtional metadata associated with the redemption.","nullable":true}},"additionalProperties":false},"MemberRewardDetails":{"required":["available","cost","id","name","type"],"type":"object","properties":{"id":{"type":"string","description":"The unique id for the reward.","format":"uuid"},"cost":{"type":"integer","description":"The cost in reward points.","format":"int32","example":10},"type":{"$ref":"#/components/schemas/RewardType"},"name":{"type":"string","description":"The name of the reward.","nullable":true,"example":"Free P&P"},"available":{"type":"boolean","description":"Whether the reward is available for redemption."}},"additionalProperties":false},"MemberRuleDetails":{"required":["alreadyFulfilled","definition","id","points","type"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the rule.","format":"uuid"},"points":{"type":"integer","description":"The reward points associated with the rule.","format":"int32","example":5},"type":{"$ref":"#/components/schemas/RuleType"},"definition":{"type":"object","description":"The definition of the rule.","nullable":true,"example":"{}"},"alreadyFulfilled":{"type":"boolean","description":"Whether the rule has been already fulfilled for the member.","nullable":true,"example":false}},"additionalProperties":false},"MemberTierProgress":{"required":["currentPointsProgress","currentTier","nextTier","requiredPointsForNextTier"],"type":"object","properties":{"currentTier":{"allOf":[{"description":"The members current reward tier."},{"$ref":"#/components/schemas/TierDefinition"}]},"nextTier":{"allOf":[{"description":"The members next potential reward tier."},{"$ref":"#/components/schemas/TierDefinition"}]},"currentPointsProgress":{"minimum":0,"type":"integer","description":"The reward points accumulated towards the the next reward tier.","format":"int32","example":15},"requiredPointsForNextTier":{"type":"integer","description":"The number of points required to qualify for the next reward tier.","format":"int32","nullable":true,"example":100}},"additionalProperties":false},"RewardDetails":{"required":["cost","couponCodePrefix","definition","enabled","id","name","tiers","type"],"type":"object","properties":{"id":{"type":"string","description":"The unique id for the reward.","format":"uuid"},"type":{"allOf":[{"description":"The reward type."},{"$ref":"#/components/schemas/RewardType"}]},"name":{"type":"string","description":"The name of the reward.","nullable":true,"example":"Free P&P"},"enabled":{"type":"boolean","description":"Whether the reward is enabled or not."},"cost":{"type":"integer","description":"The cost of this reward in points.","format":"int32","nullable":true,"example":50},"definition":{"type":"object","description":"The reward definition.","nullable":true},"tiers":{"type":"array","description":"The reward tiers this reward is available to.","nullable":true,"items":{"$ref":"#/components/schemas/RewardTierDetails"}},"couponCodePrefix":{"type":"string","description":"The prefix to be applied to the coupon code for this reward type.","nullable":true,"example":"pp4f_"}},"additionalProperties":false},"RewardTierDetails":{"required":["cost","enabled","level"],"type":"object","properties":{"level":{"type":"integer","format":"int32"},"cost":{"type":"integer","format":"int32"},"enabled":{"type":"boolean"}},"additionalProperties":false},"RewardType":{"type":"string","description":"The type of reward.","example":"FreeShippingCouponCode","enum":["FixedAmountDiscountCouponCode","PercentageOffWholeCartDiscountCouponCode","FreeShippingCouponCode"]},"RuleDetails":{"required":["definition","enabled","id","name","pointsAward","tiers","type"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"$ref":"#/components/schemas/RuleType"},"enabled":{"type":"boolean","description":"Whether the reward rule is enabled or not."},"name":{"type":"string","description":"The reward rules name.","nullable":true,"example":"Complete purchase"},"pointsAward":{"type":"integer","description":"The number of reward points awarded if you mee this rule.","format":"int32","nullable":true,"example":100},"definition":{"type":"object","description":"The rule definition.","nullable":true},"tiers":{"type":"array","description":"The reward tiers this rule applies to.","nullable":true,"items":{"$ref":"#/components/schemas/RuleTierDetails"}}},"additionalProperties":false},"RuleTierDetails":{"required":["enabled","level","pointsAward"],"type":"object","properties":{"level":{"minimum":0,"type":"integer","description":"The reward rule level.","format":"int32","example":2},"pointsAward":{"type":"integer","description":"The number of reward points awarded if you mee this rule.","format":"int32","example":200},"enabled":{"type":"boolean","description":"Whether the reward rule is enabled or not at this level."}},"additionalProperties":false},"RuleType":{"type":"string","description":"The reward rules type.","example":"Purchase","enum":["Purchase","SignUp","Birthday","Anniversary","SocialEngagement"]},"TierDefinition":{"required":["id","name","pointsThreshold"],"type":"object","properties":{"id":{"type":"string","description":"The unique id for the reward tier.","format":"uuid"},"name":{"type":"string","description":"The name of the reward tier.","nullable":true,"example":"first_purchasers"},"pointsThreshold":{"minimum":0,"type":"integer","description":"The number of points required to qualify for this reward tier.","format":"int32","example":1}},"additionalProperties":false},"TierDetails":{"required":["achievedDate","id","level","name"],"type":"object","properties":{"id":{"type":"string","description":"The unique id for this record.","format":"uuid"},"achievedDate":{"type":"string","description":"The date and time when the member achieved this reward tier in UTC.","format":"date-time"},"name":{"type":"string","description":"The name of the reward tier.","nullable":true,"example":"First purchase"},"level":{"minimum":0,"type":"integer","description":"The tier hierarchy level.","format":"int32","example":1}},"additionalProperties":false},"inline_response_200":{"allOf":[{"description":"The members details."},{"$ref":"#/components/schemas/MemberDetails"}]}},"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}}},"x-samples-languages":["curl","csharp","java","javascript","node","python","php","ruby"]}