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.
note
Before implementing any rewards program, please read Unit's Rewards guide.
Creates a reward resource.
| Verb | POST |
| Url | https://api.s.unit.sh/rewards |
| Required Scope | rewards-write |
| Data Type | reward |
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. 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. |
| 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.
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 a reward by id.
| Verb | GET |
| Url | https://api.s.unit.sh/rewards/{id} |
| Required Scope | rewards |
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 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 rewards resources. Filtering, paging and sorting can be applied.
| Verb | GET |
| Url | https://api.s.unit.sh/rewards |
| Required Scope | rewards |
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" } } } } ]}