Rewards

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

AuthorizationstringRequired

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

/rewards/programs

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

AuthorizationstringRequired

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

/rewards/accounts/{reward_account_id}

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"
      }
    ]
  }
}

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

AuthorizationstringRequired

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

/rewards/accounts/{reward_account_id}

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"
  }
}

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

AuthorizationstringRequired

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

/rewards/accounts/{reward_account_id}/transactions

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
    }
  ]
}

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

AuthorizationstringRequired

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

/rewards/accounts

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

AuthorizationstringRequired

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

/rewards/accounts/{reward_account_id}/rewards

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

AuthorizationstringRequired

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

/rewards/accounts/{reward_account_id}/gifts

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

AuthorizationstringRequired

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

/rewards/accounts/{reward_account_id}/points

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

AuthorizationstringRequired

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

/rewards/accounts/{reward_account_id}/rewards/redemptions

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

AuthorizationstringRequired

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

/rewards/accounts/{reward_account_id}/gifts/redemptions

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"
  }
}

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

AuthorizationstringRequired

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

/rewards/confirmation

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

AuthorizationstringRequired

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

/rewards/reversal

POST /rewards/reversal?request_id=text HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Accept: */*

No content

PreviousProducts NextStores

Last updated 2 years ago

Was this helpful?