Skip to main content

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.

VerbPOST
Urlhttps://api.s.unit.sh/rewards
Required Scoperewards-write
Data Typereward
Timeout (Seconds)5

Attributes#

NameTypeDescription
amountintegerThe amount (in cents) to reward the account.
descriptionstringDescription of the reward (maximum of 50 characters).
tagsobjectOptional. See Tags.
idempotencyKeystringOptional, but strongly recommended . See Idempotency.

Relationships#

NameTypeDescription
receivingAccountJSON:API RelationshipThe account that will receive the reward.
fundingAccountJSON:API RelationshipOptional. The account that will fund the reward, default is the revenue account for deposit account rewards. Not supported for credit accounts.
rewardedTransactionJSON:API RelationshipOptional. 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#

FieldTypeDescription
dataRewardThe 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.

VerbGET
Urlhttps://api.s.unit.sh/rewards/{id}
Required Scoperewards
Timeout (Seconds)5

Query Parameters#

NameTypeDefaultDescription
includestring(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#

FieldTypeDescription
dataRewardReward resource.
includedArray of DepositAccount or CreditAccount or Customer or TransactionArray 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.

VerbGET
Urlhttps://api.s.unit.sh/rewards
Required Scoperewards
Timeout (Seconds)5

Query Parameters#

NameTypeDefaultDescription
page[limit]integer100Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Number 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.
sortstringsort=-createdAtOptional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
includestring(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#

FieldTypeDescription
dataArray of RewardArray of rewards resources.
includedArray of DepositAccount or Customer or TransactionArray 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"          }        }      }    }  ]}