Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Custom rewards via API

This article's section starts at 0:00 in the video.

The Custom (API) program type lets you reward anything DollarBack can't see on its own: product reviews, UGC submissions, in-store visits, quiz completions. You define the reward in the admin; your server triggers it with one API call.

Prerequisites

  • A Merchant API key; generate one under DollarBack admin → Merchant API (also reachable from Settings → Developer API). See Merchant API: keys & endpoints.

  • A server to call the endpoint from. Never call the Merchant API from storefront JavaScript; the key must stay server-side.

Step 1: Create the custom config

  1. Open DollarBack admin → Cashback and choose the Custom (API) type.

  2. Set the credit amount and optional start/end dates.

  3. In the API Reward section, optionally check Limit how many times each customer can earn this reward and set the frequency fields. Limits are enforced server-side on every API call.

  4. Save, enable the config, and copy its config ID. Your server needs it.

Custom rewards are granted only when you call the endpoint with this config's ID. They are never triggered by Shopify webhooks or storefront actions.

Step 2: Call the endpoint

Header
Value

X-DollarBack-Shop

your-store.myshopify.com

Authorization

Bearer <your API key>

Content-Type

application/json

Body field
Type
Required
Meaning

configId

string

Yes

The custom config's ID from Step 1

customerId

string or number

Yes

The numeric Shopify customer ID

customerCurrency

string

Yes

Currency to credit in, e.g. "USD"

Example:

The exact request base URL, your key, and a copy-ready snippet are shown on the Merchant API page in the admin.

Responses

Status
Body
Meaning

200

{ "success": true, "requestId": "…", "message": "Custom reward is being processed" }

Accepted; the credit is processed asynchronously and lands within a few seconds

400

{ "error": "invalid_config", "reason": "not_found" | "not_custom" | "disabled" | "not_scheduled" }

The configId doesn't exist, isn't a Custom (API) config, is disabled, or is outside its date window

400

{ "error": "missing_fields: …" } or { "error": "invalid_json" }

Malformed request

401

{ "error": "unauthorized" }

Wrong or missing API key / shop header

500

{ "error": "internal" }

Retry later

Passing another config type's ID returns 400 invalid_config with reason not_custom; only configs created as Custom (API) can be dispatched through this endpoint. Per-customer frequency limits are enforced server-side, so a limited customer isn't credited again.

Verify it works

  1. Send the request for a test customer and confirm the 200 response.

  2. Within a few seconds the credit appears in DollarBack admin → Analytics → Activity, tagged with the config name.

  3. The customer sees the balance in the widget and account, and receives the credited email if enabled.

Common issues

  • 401 unauthorized: key revoked or headers wrong; regenerate under Merchant API: keys & endpoints.

  • 200 but no credit: check the config's frequency limit and the customer ID; then A customer didn't receive cashback.

  • Credit in the wrong currency: customerCurrency controls the credited currency; send the customer's own currency.

Related articles

PreviousSet up social follow rewardsNextHow cashback is calculated

Last updated