There is no type or direction field. A positive amount issues credit and a negative one reverses credit previously issued; issues_at decides whether it is spendable now or later. Redemption is never posted through this API — Onward owns it through the discount code — so classification is derived on our side and returned for information only.
To reverse an entry that is still pending issuance, post the negative amount carrying that entry's future issues_at; omit issues_at to reverse credit that has already issued.
The ID of the parent discount that the reward is tied to — not the discount code, and not one of Onward's internal IDs. Read it from the customer's rewards array. Onward rewrites this value if it has to recreate a discount that was deleted, so treat a 404 here as a signal to re-read GET /customers/{shopCustomerId} and pick up the current value.
The entry's ID in your platform. Unique and stable: it addresses the entry and de-duplicates writes, the same way shop_order_id does for orders. It is what makes a forwarder safe to retry. Avoid / and . — the value travels in a URL path segment.
Positive to credit; negative to reverse credit previously issued. Currency must match the reward's currency. Onward derives the presentment and USD amounts itself — do not send them.
A future timestamp holds the entry as pending issuance until then, after which it becomes spendable. Omit for immediately spendable credit — a past or present value is rejected rather than treated as immediate, so there is exactly one way to express "spendable now". The field is cleared once the entry issues, so a matured entry reports null.
Where the entry came from. name is a stable lowercase slug assigned when your integration is onboarded, and it is the only key Onward reads — it attributes the entry to the platform that sent it, since the API key resolves to a shop rather than to a caller. Every other key belongs to you: Onward stores it verbatim, surfaces it for support, and never interprets it. Keep it a flat object of string values with a small number of keys. There is deliberately no Onward vocabulary for why credit was earned, so your own reason travels here.
{ "name": "inveterate", "reason": "SIGNUP_STORE_CREDIT" }
- https://app.useonward.com/api/v1https://app.useonward.com/api/v1/rewards/{shopRewardId}/transactions
curl -i -X POST \
https://app.useonward.com/api/v1/rewards/1234567890/transactions \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-d '{
"shop_transaction_id": "inveterate:1a2b3c",
"amount": {
"cents": 1299,
"currency": "USD"
},
"issues_at": "2019-08-24T14:15:22Z",
"source_details": {
"name": "inveterate",
"reason": "SIGNUP_STORE_CREDIT"
}
}'Successful operation
Null for entries Onward issued itself, which are therefore not individually addressable.
Derived by Onward and returned for information only.
Where the entry came from. name is a stable lowercase slug assigned when your integration is onboarded, and it is the only key Onward reads — it attributes the entry to the platform that sent it, since the API key resolves to a shop rather than to a caller. Every other key belongs to you: Onward stores it verbatim, surfaces it for support, and never interprets it. Keep it a flat object of string values with a small number of keys. There is deliberately no Onward vocabulary for why credit was earned, so your own reason travels here.
{ "name": "inveterate", "reason": "SIGNUP_STORE_CREDIT" }
{ "shop_transaction_id": "inveterate:1a2b3c", "amount": { "cents": 1299, "currency": "USD" }, "classification": "issued", "issues_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "source_details": { "name": "inveterate", "reason": "SIGNUP_STORE_CREDIT" }, "reward": { "shop_reward_id": "1234567890", "balance": { … }, "pending_issuance_balance": { … }, "lifetime_issued": { … }, "lifetime_used": { … }, "lifetime_refunded": { … }, "redemption_details": { … }, "balance_updated_at": "2019-08-24T14:15:22Z" } }