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 |
#
AttributesName | 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. |
#
RelationshipsName | 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" } } } }}'
#
ResponseResponse is a JSON:API document.
#
201 CreatedField | 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 ParametersName | 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 |
#
ResponseResponse is a JSON:API document.
#
200 OKField | 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 ParametersName | 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}"
#
ResponseResponse is a JSON:API document.
#
200 OKField | 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" } } } } ]}