Merchant API: keys & endpoints
This article's section starts at 1:39 in the video.
The Merchant API lets your own backend read your cashback configuration and trigger rewards: birthdays collected in your mobile app, social follows verified by your own system, or fully custom rewards. This article covers key management, authentication, and all four endpoints.
Prerequisites
A server-side environment to call the API from. The key must never ship in client or browser code.
For the birthday, social, and custom endpoints: a matching cashback config of that type, enabled (see Custom rewards via API).
Manage your API key
Open DollarBack admin → Merchant API. The page has two sections: API key and Endpoints.
Click Generate API key to create your first key. Use Show key / Hide key to reveal it and Copy to copy it.
To replace a compromised or leaked key, click Rotate. Rotation issues a new key and the old one stops authenticating, so update your servers immediately after rotating.
The admin page says it plainly: "Use this key only from your server runtime — never in client/browser code". Anyone with the key can credit rewards on your store. Keep it in server-side environment variables, out of repositories, and rotate it if it ever leaks.
Authentication
Every request needs two headers:
A missing or wrong key returns 401 {"error": "unauthorized"}. Unexpected server errors return 500 {"error": "internal"}.
GET /api/v1/merchant/config
Returns your enabled cashback configurations and tier setup. Use it to discover config IDs for the POST endpoints and to render program details in your own UI.
Success (200):
The endpoint URLs (with your app host filled in) are listed with Copy buttons in the Endpoints section of the Merchant API page.
POST /api/v1/merchant/birthday
Submits a customer's birthday and schedules the birthday credit, the API equivalent of the widget's birthday form.
customerId
string or number
The Shopify customer ID.
birthday
object
{ "day": 14, "month": 3, "year": 1992 }
configId
string
The birthday config's ID (from GET /config).
customerCurrency
string
Currency to credit in.
Success (200):
Errors: 400 {"error": "missing_fields"} or {"error": "invalid_birthday"}, 404 {"error": "Birthday config not found"}.
POST /api/v1/merchant/social
Claims a social-follow reward for a customer. Use it when your own system verifies the follow.
customerId
string or number
The Shopify customer ID.
socialUrl
string
The social link the customer followed.
configId
string
The social config's ID.
customerCurrency
string
Currency to credit in.
Success (200): {"success": true, "message": "Social follow reward is being processed"}. The credit is processed asynchronously; verify it in the credit log rather than expecting it in the response.
Errors: 400 {"error": "missing_fields"}.
POST /api/v1/merchant/custom
Dispatches a custom (API-only) reward, the endpoint behind Custom rewards via API. Credit any behavior you can detect: reviews, referral milestones, offline events.
configId
string
Must be a custom-type config that is enabled.
customerId
string or number
The Shopify customer ID.
customerCurrency
string
Currency to credit in.
Success (200): {"success": true, "requestId": "...", "message": "Custom reward is being processed"}. Keep the requestId for support and deduplication.
Errors: 400 {"error": "missing_fields"}, {"error": "invalid_json"}, or {"error": "invalid_config", "reason": "not_found" | "not_custom" | "disabled" | "not_scheduled"}. The reason tells you whether the config ID is wrong, isn't a custom config, or is turned off.
Verify it works
Call GET /config first: a 200 with your configurations confirms your key and headers. Then fire one POST for a test customer and watch DollarBack admin → Analytics → Activity for the credit (processing is asynchronous; allow a few minutes).
Common issues
401 unauthorized: wrong or rotated key, or a missingX-DollarBack-Shopheader.invalid_configon/custom: the config ID isn't a custom config, or the config is disabled.The POST returned 200 but no credit appears: processing is asynchronous; check Activity: credit logs & scheduled rewards after a few minutes.
Related articles
Last updated