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.

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

Attributes#

NameTypeDescription
amountintegerThe amount (in cents) to reward the account.
descriptionstringDescription of the reward (maximum of 50 characters).
tagsobjectOptional. See Tags.
idempotencyKeystringOptional. 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.
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

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

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