Developer Guides
  • Introduction
    • Welcome
  • Core
    • Overview
    • Frontend
      • Implementation & Testing
      • Using the API endpoints
      • Gift cards
        • Gift Card validation API (Optional)
      • Check stock
      • Sibling products
      • Rewards program
      • Customer signatures
      • Retail transactions
      • Shopify Local Pick-up
  • API
    • Overview
    • Quick Start
    • Accounts
    • Changelog
    • Reference
      • Customers
      • Inventory
      • Orders
      • Products
      • Rewards
      • Stores
      • Vouchers
      • Staff
Powered by GitBook
On this page

Was this helpful?

Export as PDF
  1. API
  2. Reference

Rewards

PreviousProductsNextStores

Last updated 1 year ago

Was this helpful?

Our base domain URL is https://api.dotapparel.io.

Retrieves a list of reward program details

get

Scope: visitor and above

This endpoint retrieves information about reward programs in the Apparel21.

The endpoint returns a list of object that includes information such as reward program id, name, tiers, and gifts.

Authorizations
Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Responses
200
Successful response
application/json
401
Unauthorized: The user is not authorized to perform this action.
get
GET /rewards/programs HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Accept: */*

{
  "data": [
    {
      "id": 1,
      "name": "Retail Rewards",
      "description": "cs16200",
      "tiers": [
        {
          "id": 1,
          "name": "Cotton",
          "description": "Annual Spend $0 - $599",
          "sequence": 1,
          "accrualSpend": "1",
          "accrualPoints": 1,
          "autoRewardPointThreshold": 300,
          "autoRewardValue": 30,
          "autoRewardGiftId": null,
          "tierPointsBonus": 0,
          "tierRewardsBonus": 0,
          "tierGiftBonusId": null,
          "defaultPointsExpiry": {
            "months": 12,
            "days": 0
          },
          "defaultRewardExpiry": {
            "months": 0,
            "days": 60
          },
          "qualifySpend": "600",
          "qualifyPeriod": {
            "months": 12,
            "days": 0
          }
        }
      ],
      "gifts": [
        {
          "id": 1,
          "name": "Birthday Gift Cashmere",
          "description": "",
          "giftStyles": [
            {
              "id": 6821,
              "code": "CSC1016",
              "name": "Block Colour Scarf"
            },
            {
              "id": 6821,
              "code": "CSC1016",
              "name": "Empire Beanie"
            },
            {
              "id": 8085,
              "code": "PL21104",
              "name": "Flinders Touch Gloves"
            }
          ]
        }
      ]
    }
  ]
}

Retrieves a single reward account details by reward account id

get

Scope: visitor and above

This endpoint retrieves information about a single reward account in the Apparel21 system by accepting a required reward account id parameter.

The endpoint returns an object that includes information such as the associated program id, tier, rewards list, gift list and etc.

Authorizations
Path parameters
reward_account_idnumberRequired

The Apparel21 reward account id

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Responses
200
Successful response
application/json
400
Bad Request: The reward account id must be a number.
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: The reward account with the specified id does not exist.
get
GET /rewards/accounts/{reward_account_id} HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Accept: */*

{
  "data": {
    "id": 22672,
    "programId": 1,
    "programName": "Retail Rewards",
    "tierId": 2,
    "tierName": "Merino",
    "personId": 73152,
    "tierLockedUntilDate": "2023-09-01",
    "availablePoints": 0,
    "availableRewards": 200,
    "joinDate": "2021-05-03",
    "tierJoinDate": "2021-05-03",
    "pointsToNextReward": 300,
    "spendToNextReward": 300,
    "nextTierId": 3,
    "spendToNextTier": 1800,
    "pointsList": [
      {
        "createdDateTime": "2018-01-15",
        "description": "Social Media post",
        "total": 100,
        "redeemed": 20,
        "pendingRedemption": 10,
        "available": 70,
        "expiryDate": "2018-01-15"
      }
    ],
    "rewards": [
      {
        "total": 50,
        "expiryDate": "2023-12-30",
        "description": "DotApparel Rewards TEST",
        "redeemed": 0,
        "rewardId": 43923,
        "available": 50,
        "createdDateTime": "2023-04-13T13:19:36",
        "pendingRedemption": 0
      },
      {
        "total": 150,
        "expiryDate": "2023-12-30",
        "description": "DotApparel Rewards TEST",
        "redeemed": 0,
        "rewardId": 43924,
        "available": 150,
        "createdDateTime": "2023-04-13T13:19:45",
        "pendingRedemption": 0
      }
    ],
    "gifts": [
      {
        "giftName": "Welcome To Merino",
        "expiryDate": "2023-06-12",
        "description": "Merino Tier Bonus",
        "giftId": 4,
        "issueId": 38559,
        "createdDateTime": "2023-04-13T13:23:16"
      },
      {
        "giftName": "Birthday Gift Merino",
        "expiryDate": "2023-12-31",
        "description": "Test Gift 1",
        "giftId": 2,
        "issueId": 38560,
        "createdDateTime": "2023-04-13T13:24:35"
      }
    ]
  }
}

Retrieves a history of all points and reward accruals and redemptions

get

Scope: visitor and above

This endpoint retrieves transaction history of a single reward account in Apparel21.

The endpoint returns an object that includes information such as the associated program id, tier, rewards list, gift list and etc.

Authorizations
Path parameters
reward_account_idnumberRequired

The Apparel21 reward account id

Query parameters
from_datestringOptional

(Optional) Earliest date to retrieve transaction from yyyy-MM-dd format

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Responses
200
Successful response
application/json
400
Bad Request: The reward account id must be a number.
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: The reward account with the specified id does not exist.
404
Not Found: No data found
get
GET /rewards/accounts/{reward_account_id}/transactions HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Accept: */*

{
  "data": [
    {
      "transactionDateTime": "2021-05-03T12:38:42",
      "description": "Birthday Reward",
      "source": "Retail API",
      "reference": "D0123455",
      "spend": 100,
      "points": 50,
      "rewardAmount": 10,
      "giftId": 4,
      "giftName": "Welcome To Merino",
      "newGift": true,
      "redeemedGiftSkuId": 1541,
      "confirmed": true
    }
  ]
}

Confirms reward redemption

post

Scope: maintainer and above

This endpoint confirms an unconfirmed request and commit the pending redemption of points or rewards.

This endpoint must accept a request id which is obtained from redeem reward or gift endpoint.

The endpoint returns 201 code if successful.

Authorizations
Query parameters
request_idstringRequired

Request id obtained from redeem reward or gift endpoint

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Responses
201
Successful operation
400
Bad Request: Request id cannot be empty
401
Unauthorized: The user is not authorized to perform this action.
500
Internal Server Error: Request ID has already been posted
post
POST /rewards/confirmation?request_id=text HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Accept: */*

No content

Reverses reward redemption

post

Scope: maintainer and above

This endpoint reverses an unconfirmed request. This can only be done within 24 hours of a redemption request

This endpoint must accept a request id which is obtained from redeem reward or redeem gift endpoint.

The endpoint returns 201 code if successful.

Authorizations
Query parameters
request_idstringRequired

Request id obtained from redeem reward or gift endpoint

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Responses
201
Successful operation
400
Bad Request: Request id cannot be empty
401
Unauthorized: The user is not authorized to perform this action.
500
Internal Server Error: Request ID has already been posted
post
POST /rewards/reversal?request_id=text HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Accept: */*

No content
  • GETRetrieves a list of reward program details
  • GETRetrieves a single reward account details by reward account id
  • PUTUpdates a person's tier information
  • GETRetrieves a history of all points and reward accruals and redemptions
  • POSTCreates a reward account for a person
  • POSTCreates a new reward to a person's reward account
  • POSTCreates a new gift to a person's reward account
  • POSTAdd points to a person's reward account
  • POSTRedeems a reward from a person's reward account
  • POSTRedeems a reward from a person's reward account
  • POSTConfirms reward redemption
  • POSTReverses reward redemption

Updates a person's tier information

put

Scope: maintainer and above

This endpoint updates a person's tier information.

The endpoint returns an object that includes information such as the reward account id, program id, program name, tier details that the person is associated with.

Authorizations
Path parameters
reward_account_idnumberRequired

The Apparel21 Reward account ID

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Body
tierIdnumberRequiredExample: 2
personIdnumberRequiredExample: 73152
tierLockedUntilDatestringOptionalExample: 2019-09-01
Responses
200
Successful response
application/json
400
Bad Request: The request body was invalid.
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: The specified PersonId does not match the specified AccountId. Forbidden: Invalid Tier Id. Forbidden: The specified AccountId does not exist.
put
PUT /rewards/accounts/{reward_account_id} HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "tierId": 2,
  "personId": 73152,
  "tierLockedUntilDate": "2019-09-01"
}
{
  "data": {
    "id": 22672,
    "programId": 1,
    "programName": "Retail Rewards",
    "tierId": 2,
    "tierName": "Merino",
    "personId": 73152,
    "tierLockedUntilDate": "2023-09-01"
  }
}

Creates a reward account for a person

post

Scope: maintainer and above

This endpoint adds a person to a rewards program.

This creates a reward account for the person and marks the new account as active'

The endpoint returns an object that includes information such as the reward account id, program id, program name, tier details that the person is associated with.

Authorizations
Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Body
programIdnumberRequiredExample: 1
tierIdnumberRequiredExample: 2
personIdnumberRequiredExample: 73152
Responses
201Success
application/json
400
Bad Request: The request body was invalid.
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: Account already exists for the specified PersonId and ProgramId. Forbidden: The specified TierId is not valid for the specified ProgramId.
post
POST /rewards/accounts HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "programId": 1,
  "tierId": 2,
  "personId": 73152
}
{
  "id": 22672,
  "programId": 1,
  "programName": "Retail Rewards",
  "tierId": 2,
  "tierName": "Merino",
  "personId": 73152,
  "tierLockedUntilDate": "2023-09-01"
}

Creates a new reward to a person's reward account

post

Scope: maintainer and above

This endpoint creates a reward for a reward account.

This endpoint must accept personId, description, and amount in the request body. The rest are optional.

The endpoint returns 201 status code if request is successful.

Authorizations
Path parameters
reward_account_idnumberRequired

The Apparel21 Reward account ID

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Body
personIdnumberRequiredExample: 73152
descriptionstringRequiredExample: DotApparel Rewards TEST
amountnumberRequiredExample: 50
expiryDatestringRequiredExample: 2023-12-30
issueReasonIdnumberRequiredExample: 17666
referencestringRequiredExample: SM1
Responses
201
Successful operation
400
Bad Request: The request body was invalid.
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: The specified person id does not match the specified account id Forbidden: The specified account id does not exist Forbidden: The specified issue reason id is invalid
post
POST /rewards/accounts/{reward_account_id}/rewards HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Content-Type: application/json
Accept: */*
Content-Length: 136

{
  "personId": 73152,
  "description": "DotApparel Rewards TEST",
  "amount": 50,
  "expiryDate": "2023-12-30",
  "issueReasonId": 17666,
  "reference": "SM1"
}
No content

Creates a new gift to a person's reward account

post

Scope: maintainer and above

This endpoint creates a gift for a reward account.

This endpoint must accept personId, description, and gift id in the request body. The rest are optional.

The endpoint returns 201 status code if request is successful.

Authorizations
Path parameters
reward_account_idnumberRequired

The Apparel21 Reward account ID

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Body
personIdnumberRequiredExample: 73152
giftIdnumberRequiredExample: 2620
descriptionstringRequiredExample: Test gift
expiryDatestringRequiredExample: 2023-12-30
issueReasonIdnumberRequiredExample: 17666
referencestringRequiredExample: AUG123
Responses
201
Successful operation
400
Bad Request: The request body was invalid.
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: The specified GiftId is not valid for the specified account id Forbidden: The specified PersonId does not match the specified account id Forbidden: The specified account id does not exist Forbidden: The specified issue reason id is invalid
post
POST /rewards/accounts/{reward_account_id}/gifts HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "personId": 73152,
  "giftId": 2620,
  "description": "Test gift",
  "expiryDate": "2023-12-30",
  "issueReasonId": 17666,
  "reference": "AUG123"
}
No content

Add points to a person's reward account

post

Scope: maintainer and above

This endpoint adds points to a person's reward account.

This endpoint must accept personId, points, and description id in the request body. The rest are optional.

The endpoint returns 201 status code if request is successful.

Authorizations
Path parameters
reward_account_idnumberRequired

The Apparel21 Reward account ID

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Body
personIdnumberRequiredExample: 73152
pointsnumberRequiredExample: 100
descriptionstringRequiredExample: Test gift
expiryDatestringRequiredExample: 2023-12-30
referencestringRequiredExample: AUG123
Responses
201
Successful operation
400
Bad Request: The request body was invalid.
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: The specified person id does not match the specified account id Forbidden: The specified account id does not exist
post
POST /rewards/accounts/{reward_account_id}/points HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "personId": 73152,
  "points": 100,
  "description": "Test gift",
  "expiryDate": "2023-12-30",
  "reference": "AUG123"
}
No content

Redeems a reward from a person's reward account

post

Scope: maintainer and above

This endpoint redeems a reward from a person's reward account.

This endpoint must accept personId, description, spend amount, amount, reference and auto confirm as part of the request body.

The endpoint returns a request id that can be used on confirm or reversed unconfirmed request endpoint.

Authorizations
Path parameters
reward_account_idnumberRequired

The Apparel21 Reward account ID

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Body
personIdnumberRequiredExample: 73152
descriptionstringRequiredExample: Redeem reward
spendAmountnumberRequiredExample: 50
amountnumberRequiredExample: 30
referencestringRequiredExample: RED123
autoConfirmbooleanRequiredExample: true
Responses
201
Successful response
application/json
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: The specified person id does not match the specified account id Forbidden: The specified account id does not exist
post
POST /rewards/accounts/{reward_account_id}/rewards/redemptions HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "personId": 73152,
  "description": "Redeem reward",
  "spendAmount": 50,
  "amount": 30,
  "reference": "RED123",
  "autoConfirm": true
}
{
  "data": {
    "requestId": "6b42837e-eee3-4d81-abb5-d4b26d202a40"
  }
}

Redeems a reward from a person's reward account

post

Scope: maintainer and above

This endpoint redeems a reward from a person's reward account.

This endpoint must accept personId, description, spend amount, amount, reference and auto confirm as part of the request body.

The endpoint returns a request id that can be used on confirm or reversed unconfirmed request endpoint.

Authorizations
Path parameters
reward_account_idnumberRequired

The Apparel21 Reward account ID

Header parameters
X-DotApparel-NamestringRequired

An alias name that represents a particular brand that is using the API

shopstringRequired
Body
personIdnumberRequiredExample: 73152
descriptionstringRequiredExample: Redeem reward
giftIdnumberRequiredExample: 2
redeemedSkuIdnumberRequiredExample: 6821
referencestringRequiredExample: RED123
autoConfirmbooleanRequiredExample: true
Responses
201
Successful response
application/json
401
Unauthorized: The user is not authorized to perform this action.
403
Forbidden: The specified person id does not match the specified account id Forbidden: The specified account id does not exist Forbidden: The specified redeemed sku id is invalid for the specified gift id Forbidden: No gift with the specified gift id is available to redeem
post
POST /rewards/accounts/{reward_account_id}/gifts/redemptions HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "personId": 73152,
  "description": "Redeem reward",
  "giftId": 2,
  "redeemedSkuId": 6821,
  "reference": "RED123",
  "autoConfirm": true
}
{
  "data": {
    "requestId": "6b42837e-eee3-4d81-abb5-d4b26d202a40"
  }
}