Skip to main content
POST
/
v1
/
rewards
Give stock
curl --request POST \
  --url https://api.stockly.com/v1/rewards \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "userId": "6f1d2a3b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
  "idempotencyKey": "order-1001-reward",
  "amountUsd": 5.25,
  "assetSymbol": "AAPL",
  "source": "cashback",
  "metadata": {
    "orderId": "1001"
  }
}
'
{
  "reward": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "appId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "idempotencyKey": "<string>",
    "amountUsd": 123,
    "assetSymbol": "<string>",
    "source": "<string>",
    "metadata": {},
    "createdAt": "2023-11-07T05:31:56Z",
    "executedAt": "2023-11-07T05:31:56Z",
    "failureReason": "<string>"
  },
  "status": "<string>",
  "idempotentReplay": true
}

Authorizations

​
x-api-key
string
header
required

Your Stockly API key. Identifies your app; you never pass an app id.

Body

application/json
​
userId
string<uuid>
required

Must reference an existing user in your app.

​
idempotencyKey
string
required

Unique per logical award. Safe to retry.

Required string length: 8 - 128
​
amountUsd
number
required

Award value in USD.

Required range: x <= 1000000
​
assetSymbol
string
required

Stock ticker from the catalog, e.g. AAPL. Normalized to uppercase.

Required string length: 1 - 16
Example:

"AAPL"

​
source
string

Optional label, e.g. cashback.

Required string length: 1 - 64
​
metadata
object

Optional arbitrary JSON, returned on reads.

Response

Idempotent replay — the award already existed and is returned unchanged

​
reward
object

A stock award. Moves from recorded to executed once fulfilled.

​
status
string
​
idempotentReplay
boolean