> For the complete documentation index, see [llms.txt](https://help.dollarlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dollarlabs.io/dollarback-store-credit/developer-tools/merchant-api-keys-and-endpoints.md). # Merchant API: keys & endpoints {% embed url="" %} *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](/dollarback-store-credit/earning-cashback-programs/custom-rewards-via-api.md)). ## Manage your API key 1. Open **DollarBack admin → Merchant API**. The page has two sections: **API key** and **Endpoints**. 2. Click **Generate API key** to create your first key. Use **Show key** / **Hide key** to reveal it and **Copy** to copy it. 3. 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. {% hint style="warning" %} 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. {% endhint %} ## Authentication Every request needs two headers: ``` X-DollarBack-Shop: your-store.myshopify.com Authorization: Bearer ``` 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. ```bash curl "https:///api/v1/merchant/config" \ -H "X-DollarBack-Shop: your-store.myshopify.com" \ -H "Authorization: Bearer " ``` Success (200): ```json { "shop": "your-store.myshopify.com", "configurations": [ ... ], "tiers": { "enabled": true, "tiers": [ ... ] } } ``` 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. | Body field | Type | Notes | | ------------------ | ---------------- | ---------------------------------------------- | | `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): ```json { "success": true, "message": "...", "data": { "customerId": "...", "birthday": { ... }, "nextCreditDate": "...", "creditAmount": ... } } ``` 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. | Body field | Type | Notes | | ------------------ | ---------------- | -------------------------------------- | | `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](/dollarback-store-credit/earning-cashback-programs/custom-rewards-via-api.md). Credit any behavior you can detect: reviews, referral milestones, offline events. | Body field | Type | Notes | | ------------------ | ---------------- | ------------------------------------------------- | | `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 missing `X-DollarBack-Shop` header. * `invalid_config` on `/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](/dollarback-store-credit/analytics-data-and-account/credit-logs-and-scheduled-rewards.md) after a few minutes. ## Related articles * [Custom rewards via API](/dollarback-store-credit/earning-cashback-programs/custom-rewards-via-api.md) * [Storefront window API (theme devs)](/dollarback-store-credit/developer-tools/storefront-window-api.md) * [Set up birthday rewards](/dollarback-store-credit/earning-cashback-programs/set-up-birthday-rewards.md) * [Set up social follow rewards](/dollarback-store-credit/earning-cashback-programs/set-up-social-follow-rewards.md)