> 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-api.md). # Developer API The Dollarback Developer API allows you to trigger loyalty rewards programmatically from your own applications. Whether you're building a Hydrogen storefront, a custom Liquid implementation, a mobile app, or another customer touchpoint, the API lets you award store credit without relying on the built-in Dollarback widgets. {% embed url="" %} Common use cases include: * Rewarding customers after completing a game or quiz * Sweepstakes and competition rewards * Mobile app loyalty programs * Birthday collection forms * Social follow rewards * Custom storefronts built with Hydrogen * Any custom workflow that needs to issue store credit *** ## Getting your API Key 1. Open the **Dollarback** app. 2. Navigate to **Settings → Developer API**. 3. Click **Manage**. 4. Generate an API key. 5. Copy the API key and keep it secure. {% hint style="info" %} **Note:** The Developer API is only available on paid plans. {% endhint %} *** ## Authentication Every request must include the following headers.
HeaderValue
X-DollarBack-Shop<shop>.myshopify.com
AuthorizationBearer <api_key>
Content-Typeapplication/json (required for POST requests only)
Example: ```http X-DollarBack-Shop: mystore.myshopify.com Authorization: Bearer your_api_key Content-Type: application/json ``` *** ## Fetch Reward Configurations Before awarding rewards, you'll typically fetch your store's reward configurations. ### Endpoint ```http GET /api/v1/merchant/config ``` ``` https://dollarback-production.dollarlabs.io/api/v1/merchant/config ``` This endpoint returns every reward configuration you've created inside Dollarback. Example response: ```json { "shop": "store.myshopify.com", "configurations": [ { "id": "b506c7e8-8ac3-4aa9-b693-41d7de4151e5", "title": "API based loyalty reward", "configType": "custom", "cashbackValue": 100 }, { "id": "29656ac8-8e9c-4b4a-a72c-079b100ed50e", "title": "Instagram", "configType": "social" }, { "id": "f1b58876-2820-431c-bc1d-d05ddf7204ae", "title": "Birthday", "configType": "birthday" } ] } ``` The most important value is the configuration **`id`**, which is required when triggering rewards. *** ## Trigger a Custom Reward Custom rewards let you issue store credit whenever an event happens outside Shopify. Examples include: * Completing a game * Winning a competition * Referral approval * Completing a survey * Manual rewards from your application ### Endpoint ```http POST /api/v1/merchant/custom ``` ``` https://dollarback-production.dollarlabs.io/api/v1/merchant/custom ``` ### Request ```json { "configId": "cfg_custom", "customerId": "1234567890", "customerCurrency": "USD" } ``` #### Parameters
FieldDescription
configIdID of your Custom reward configuration
customerIdShopify Customer ID
customerCurrencyCustomer's shopping currency
### Response ```json { "success": true, "requestId": "9b7f...", "message": "Custom reward is being processed" } ``` The returned `requestId` can be used for tracking and debugging. *** ## Submit a Birthday If you're collecting birthdays through your own forms or mobile app, use this endpoint to save the customer's birthday inside Dollarback. The customer will automatically receive birthday rewards according to the rules configured inside the app. ### Endpoint ```http POST /api/v1/merchant/birthday ``` ``` https://dollarback-production.dollarlabs.io/api/v1/merchant/birthday ``` ### Request ```json { "customerId": "1234567890", "birthday": { "day": 12, "month": 4, "year": 1992 }, "configId": "cfg_abc", "customerCurrency": "USD" } ``` #### Parameters
FieldDescription
customerIdShopify Customer ID
birthdayBirthday object containing day, month and year
configIdBirthday reward configuration ID
customerCurrencyCustomer's shopping currency
### Response ```json { "success": true, "message": "Birthday submitted successfully", "data": { "customerId": "1234567890", "birthday": { "day": 12, "month": 4, "year": 1992 }, "nextCreditDate": "2027-04-12", "creditAmount": 500 } } ``` The response includes: * The saved birthday * The next reward date * The amount of store credit that will be awarded *** ## Trigger a Social Follow Reward If customers follow your brand through a custom application or website instead of the built-in Dollarback widget, use this endpoint. ### Endpoint ```http POST /api/v1/merchant/social ``` ``` https://dollarback-production.dollarlabs.io/api/v1/merchant/social ``` ### Request ```json { "customerId": "1234567890", "socialUrl": "https://instagram.com/yourshop", "configId": "cfg_social", "customerCurrency": "USD" } ``` #### Parameters
FieldDescription
customerIdShopify Customer ID
socialUrlSocial profile URL being rewarded
configIdSocial reward configuration ID
customerCurrencyCustomer's shopping currency
### Response ```json { "success": true, "message": "Social follow reward is being processed" } ``` *** ## Currency Conversion Dollarback automatically converts rewards into the customer's currency. For example: * Your reward configuration awards **100 INR** * The customer shops in **USD** * Send `"customerCurrency": "USD"` Dollarback will automatically calculate the equivalent reward amount using current exchange rates. Always pass the customer's shopping currency to ensure they receive rewards in the currency they use while shopping. *** ## Finding the Correct Configuration ID Every reward configuration has a unique `id`. Use the **GET `/merchant/config`** endpoint to retrieve all configurations for your store. Each reward type has its own configuration ID, for example: | Reward Type | Config Type | | ----------------- | ------------ | | Birthday | `birthday` | | Instagram Follow | `social` | | Custom API Reward | `custom` | | Newsletter Signup | `newsletter` | | Welcome Bonus | `signup` | Use the matching configuration ID when calling the respective POST endpoint. *** ## Best Practices * Always use the Shopify Customer ID. * Fetch configuration IDs dynamically instead of hardcoding them. * Pass the customer's current shopping currency. * Store your API key securely. * Never expose your API key in frontend JavaScript or public applications. *** ## Example Workflow A typical integration looks like this: 1. Generate an API key from **Developer API**. 2. Call **GET `/merchant/config`** to retrieve available reward configurations. 3. Save the relevant configuration IDs. 4. When a customer completes an action (game, survey, birthday submission, social follow, etc.), call the appropriate POST endpoint. 5. Dollarback processes the reward and records it in your analytics and reporting. This approach allows you to extend Dollarback rewards across custom storefronts, Hydrogen applications, mobile apps, and any other customer touchpoint while keeping all reward tracking centralized inside Dollarback.