search

Rewards program

DotApparel will expose an endpoint POST /api-rewardsAccount that accepts an email address and returns the details of the rewards account of the given customer.

The frontend will need to call the endpoint directly to get “rewards account” details.

Rewards Account Creation

If a customer does not have any rewards account in AP21, the endpoint is able to automatically create a new rewards account and proceed with the new account. (Please note that this option should be enabled in the app’s settings)

Rewards Tier Tags Synchronisation

When Sync customer rewards tier tags is enabled in DotApparel rewards settings:

  • DotApparel will automatically add a tag in the format x-loyalty:{tierName} to the Shopify customer

  • The tag prefix (e.g., x-loyalty) is configurable in the settings

hashtag
Endpoint

Request:

POST https://{shopDomain}/apps/dotapparel/api-rewardsAccount

{
  "email": "[email protected]"
}

Response:

{
  available_rewards: "0",
  gifts: [
    {
      created_at: "2021-05-27",
      description: "Test March Gift",
      expires_at: "2023-03-06",
      gift_id: "21", // previously called "id"
      options: [
        {
          handle: "abc-123",
          shopify_id: 1234567890,
        },
      ],
    },
  ],
  join_date: "2019-03-06", 
  tier_description: "$300 - $699", 
  tier_locked_until_date: "2021-09-01",
  tier_join_date: "2021-05-27", 
  tier_name: "Tier 2", 
  next_tier_id: "4",
  next_tier_name: "Business Class",
  reward_account_id: "461116", 
  rewards: [
    {
      available: "25.00",
      id: "163421",
      created_at: "2018-08-22",
      description: "Example Reward",
      expires_at: "2023-03-06",
      redeemed: "0.00",
      total: "25.00",
    },
  ],
  spend_to_next_tier: "700.00",
}

hashtag
Adding Reward to Orders

circle-info

UI extension is available for this Reward Redemption process.

Please contact support if you have the new Shopify checkout custmosizationarrow-up-right enabled.

hashtag
Endpoints

hashtag
Get Reward Balance

Request:

Response:

hashtag
UI example

Guest checkout

Customer logged in (Hide the form if the available balance is 0)

hashtag
Form validations

It is important to ensure that all necessary validations are performed before requesting the redeem reward endpoint. The following validations are crucial:

  • The "amount to redeem" must not exceed the available balance.

  • Once the cart has a "REWARD" discount applied to it, the available balance must be calculated on the front end. Please note that the "available_rewards" value won't be reflected in the "Get Rewards Balance" API until the order is created.

hashtag
Recommended workflow

circle-info

  • The front-end team is responsible for designing the redemption solutions and workflow on the website. This includes creating a user interface for customers to enter and apply their reward amount during the checkout process.

  • The frontend team should ensure that the Discount Application Title is set to "Reward Redemption" within the Shopify Scripts implementation. This title is crucial for correctly identifying and applying the reward amount as a discount when sending an order to AP21.

  1. Make an API call to the Get Reward Balance endpoint to retrieve the available balance (available_rewards) for the customer.

  2. When a customer wishes to use their rewards, you'll need to add a "reward_amount" to the cart to trigger the Shopify Scripts that handle the rewards redemption. Follow these steps:

    • When the customer enters an amount to redeem their reward, programmatically add the relevant line item properties to the cart item(s) using Shopify's cart API.

    • Include the necessary line item properties (i.e. _reward_amount) that will be used to trigger the Shopify Scripts. These properties will indicate that the loyalty reward has been redeemed and will initiate the discount calculation.

  3. To apply the reward amount as a discount, you need to implement a Shopify Script. This script will identify the loyalty reward amount that has been redeemed in the cart and transform the reward amount into a discount. Follow these steps:

    • Create a new Shopify Script or modify an existing one to handle the loyalty reward redemption.

    • In the script, identify the relevant info from the cart by checking the line item properties (i.e. _reward_amount)

    • Calculate and apply the discount equivalent to the reward amount.

    • Ensure that the "Discount Application Title" is set to "Reward Redemption" to correctly redeem the reward amount in Apparel21.

  4. Please note each order can only have one reward discount application.

hashtag
Example discount_application of Reward Redemption in Shopify orders

hashtag
Adding a Gift Product to Orders

  • To apply the reward amount as a discount, you need to implement a Shopify Script. This script will identify the Loyalty Reward product in the cart and transform the reward amount into a discount. Follow these steps:

    • Create a new Shopify Script or modify an existing one to handle the Loyalty Reward redemption.

    • In the script, identify the Loyalty Reward product in the cart by checking the line item properties.

    • Calculate and apply the discount equivalent to the reward amount.

    • Ensure that the "Discount Application Title" is set to "Reward Redemption" to correctly redeem the reward amount in Apparel21.

Similar to the "Rewards" redemption, DotApparel also provides the available gifts in the API response that a customer earned from a reward program.

The recommended workflow:

  1. Make an API call to the DotApparel API endpoint to retrieve the available gifts for the customer.

  2. When a customer wishes to redeem a gift, they need to add the corresponding gift product to their cart along with relevant line item properties. Follow these steps:

    • When the customer selects the option to redeem a gift, programmatically add the gift card product to their cart using Shopify's cart API.

    • Include the necessary line item properties (i.e. _gift_id) that will be used to identify the gift card and trigger the Shopify Scripts.

  3. To apply the discount to gift products, you need to implement a Shopify Script. This script will adjust the price of the gift product to zero and apply the necessary discount. Follow these steps:

    • Create a new Shopify Script or modify an existing one to handle the Gift Redemption.

    • In the script, identify the gift card product in the cart by checking the line item properties.

    • Set the price of the gift card product to zero.

    • Ensure that the "Discount Application Title" is set to "Gift Redemption" to correctly apply the discount.

circle-exclamation

  • The front-end team is responsible for designing and implementing the redemption solutions and workflow on the website. This includes creating a user-friendly interface that allows customers to easily select and apply their earned gifts during the checkout process.

  • It is important to ensure that the gift products are set to a price of zero in the order. The front-end team should ensure that the necessary adjustments are made to the price of the gift product when it is added to the customer's cart.

  • During the implementation of Shopify Scripts, the front-end team should ensure that

    • The Discount Application Title is set to "Gift Redemption."

    • The discount percentage should be set to 100%, and prevent any other discounts from applying to the gift items.

  • The Discount Application Title and percentage play a crucial role in correctly identifying and processing the gift redemption when sending the order to AP21.

hashtag
Example payload of Gift Redemption discount and item in Shopify orders

PreviousSibling productsNextCustomer signatures

Last updated