Rewards

The rewards API provides you with a simple way to send rewards to customers. This is typically used to support financial benefits like cashback, referral awards and others.

For Credit Accounts, a reward will reduce the balance of the account.

note

Before implementing any rewards program, please read Unit's Rewards guide.

Create Reward

Creates a reward resource.

Verb	POST
Url	https://api.s.unit.sh/rewards
Required Scope	rewards-write
Data Type	reward
Timeout (Seconds)	5

Attributes

Name	Type	Description
amount	integer	The amount (in cents) to reward the account.
description	string	Description of the reward (maximum of 50 characters).
tags	object	Optional. See Tags.
idempotencyKey	string	Optional, but strongly recommended . See Idempotency.

Relationships

Name	Type	Description
receivingAccount	JSON:API Relationship	The account that will receive the reward.
fundingAccount	JSON:API Relationship	Optional. The account that will fund the reward, default is the revenue account for deposit account rewards. Not supported for credit accounts.
rewardedTransaction	JSON:API Relationship	Optional. The transaction that triggered the reward (mostly relevant for cashback rewards).

Example Request:

curl -X POST 'https://api.s.unit.sh/rewards'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "reward",
    "attributes": {
      "amount": 3000,
      "description": "Reward for transaction #5678"
    },
    "relationships": {
      "receivingAccount": {
        "data": {
          "type": "depositAccount",
          "id": "10000"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	Reward	The requested resource after the operation was completed.

Example Response:

{
  "data": {
    "type": "reward",
    "id": "11",
    "attributes": {
      "createdAt": "2022-03-31T09:25:56.388Z",
      "amount": 1000,
      "description": "Reward for VIP customer",
      "status": "Sent",
      "tags": {
        "customerType": "vip"
      }
    },
    "relationships": {
      "receivingAccount": {
        "data": {
          "type": "account",
          "id": "10006"
        }
      },
      "fundingAccount": {
        "data": {
          "type": "account",
          "id": "10002"
        }
      },
      "rewardedTransaction": {
        "data": {
          "type": "transaction",
          "id": "42"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10007"
        }
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id": "99"
        }
      }
    }
  }
}

Get by Id

Get a reward by id.

Verb	GET
Url	https://api.s.unit.sh/rewards/{id}
Required Scope	rewards
Timeout (Seconds)	5

Query Parameters

Name	Type	Default	Description
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account, transaction. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Reward	Reward resource.
included	Array of DepositAccount or CreditAccount or Customer or Transaction	Array of resources requested by the include query parameter.

curl -X GET 'https://api.s.unit.sh/rewards/100' \
-H "Authorization: Bearer ${TOKEN}"

List

List rewards resources. Filtering, paging and sorting can be applied.

Verb	GET
Url	https://api.s.unit.sh/rewards
Required Scope	rewards
Timeout (Seconds)	5

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Number of resources to skip. See Pagination.
filter[transactionId]	string	(empty)	Optional. Filters the results by the specified transaction id.
filter[rewardedTransactionId]	string	(empty)	Optional. Filters the results by the specified rewarded transaction id.
filter[receivingAccountId]	string	(empty)	Optional. Filters the results by the specified account id.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[cardId]	string	(empty)	Optional. Filters the results by the specified card id.
filter[status]	string	(empty)	Optional. Filter by reward Status. Usage example: filter[status][0]=Rejected.
filter[since]	RFC3339 Date string	(empty)	Optional. Filters the rewards that occurred after the specified date. e.g. 2020-01-13T16:01:19.346Z
filter[until]	RFC3339 Date string	(empty)	Optional. Filters the rewards that occurred before the specified date. e.g. 2020-01-02T20:06:23.486Z
filter[tags]	Tags (JSON)	(empty)	Optional. Filter rewards by Tags.
sort	string	sort=-createdAt	Optional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account, transaction. See Getting Related Resources

curl -X GET 'https://api.s.unit.sh/rewards?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of Reward	Array of rewards resources.
included	Array of DepositAccount or Customer or Transaction	Array of resources requested by the include query parameter.

Example Response:

{
  "data": [
    {
      "type": "reward",
      "id": "11",
      "attributes": {
        "createdAt": "2022-03-21T09:25:56.388Z",
        "amount": 1000,
        "description": "Reward for VIP customer",
        "status": "Sent",
        "tags": {
          "customerType": "vip"
        }
      },
      "relationships": {
        "receivingAccount": {
          "data": {
            "type": "account",
            "id": "10006"
          }
        },
        "fundingAccount": {
          "data": {
            "type": "account",
            "id": "10002"
          }
        },
        "rewardedTransaction": {
          "data": {
            "type": "transaction",
            "id": "42"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "10007"
          }
        }
      }
    },
    {
      "type": "reward",
      "id": "47",
      "attributes": {
        "createdAt": "2022-03-30T09:25:56.388Z",
        "amount": 2500,
        "description": "Reward for VIP customer",
        "status": "Rejected",
        "rejectReason": "InsufficientFunds",
        "tags": {
          "customerType": "vip"
        }
      },
      "relationships": {
        "receivingAccount": {
          "data": {
            "type": "account",
            "id": "10006"
          }
        },
        "fundingAccount": {
          "data": {
            "type": "account",
            "id": "10002"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "10007"
          }
        }
      }
    }
  ]
}