Rewards

Rewards are credits you issue to users or accounts for incentives, promos, or goodwill.

Anchor’s Rewards API allows organizations to move funds between deposit accounts with clear “Reward” semantics for tracking, reporting, and automation.

Use Case

Common use-cases include:

Customer incentives like signup bonuses, referral payouts, and loyalty credits.
Promotional credits for campaigns, limited-time offers, or tier upgrades.
Operational adjustments that need an auditable “reward” label rather than a fee or standard transfer.

Create Reward

Make an API call to create the reward endpoint. You must specify the source account (debited), destination account (credited), currency, amount, and optional metadata.

Verb	URL
`POST`	`{{baseUrl}}/api/v1/rewards`

Reward Sample Request:

curl --location 'https://api.getanchor.co/api/v1/rewards' \
--header 'Content-Type: application/json' \
--header 'x-anchor-key: <API Key>' \
--data '{
  "data": {
    "type": "Reward",
    "attributes": {
      "description": "Onboarding Reward",
      "currency": "NGN",
      "amount": 1000,
      "metadata": {
        "key1": "Reward",
        "key2": "Value2"
      }
    },
    "relationships": {
      "destinationAccount": {
        "data": {
          "id": "17670000004411-anc_acc", 
          "type": "DepositAccount"
        }
      },
      "sourceAccount": {
        "data": {
          "id": "1751800000082717-anc_acc", 
          "type": "DepositAccount"
        }
      }
    }
  }
}'

{
    "data": {
        "id": "176800000071511-anc_rew",
        "type": "Reward",
        "attributes": {
            "createdAt": "2026-01-18T18:04:47.152141645",
            "amount": 1000,
            "metadata": {
                "key1": "Reward",
                "key2": "Value2"
            },
            "description": "Onboarding Reward",
            "currency": "NGN",
            "status": "COMPLETED"
        },
        "relationships": {
            "sourceAccount": {
                "data": {
                    "id": "1751000000782717-anc_acc",
                    "type": "DepositAccount"
                }
            },
            "organization": {
                "data": {
                    "id": "165340000009610-anc_og",
                    "type": "Organization"
                }
            },
            "destinationAccount": {
                "data": {
                    "id": "1765800000064411-anc_acc",
                    "type": "DepositAccount"
                }
            }
        }
    }
}

Attribute	Description
`type`	Type of the resource. In this case it must be Reward
`amount`	Fixed amount in lowest currency unit (e.g., kobo)
`currency`	ISO currency code (e.g., NGN)
`description`	Short description shown in activity
`metadata`	Optional custom key-value pairs
`relationships.sourceAccount`	Account to debit (DepositAccount)
`relationships.destinationAccount`	Account to credit (DepositAccount)

Check reward status Use the response’s ‎attributes.status to determine outcome:

PENDING: The reward has been created and is awaiting processing.
COMPLETED: The reward has been successfully posted to the ledger.
FAILED: The reward did not complete; inspect events and account balances.

Errors

Common error causes include:

Detail	Description
Insufficient funds	Source account balance is lower than ‎`amount`.
Invalid account ID	Either source or destination account does not exist or is inactive in your organization.
Validation errors	Missing required fields, negative amounts, or incorrect types. Inspect the error body for specific codes and messages.