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.

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.

Note: The Developer API is only available on paid plans.

---

Authentication

Every request must include the following headers.

Header	Value
X-DollarBack-Shop	<shop>.myshopify.com
Authorization	Bearer <api_key>
Content-Type	application/json (required for POST requests only)

Example:

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

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:

{
  "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

POST /api/v1/merchant/custom

https://dollarback-production.dollarlabs.io/api/v1/merchant/custom

Request

{
  "configId": "cfg_custom",
  "customerId": "1234567890",
  "customerCurrency": "USD"
}

Parameters

Field	Description
configId	ID of your Custom reward configuration
customerId	Shopify Customer ID
customerCurrency	Customer's shopping currency

Response

{
  "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

POST /api/v1/merchant/birthday

https://dollarback-production.dollarlabs.io/api/v1/merchant/birthday

Request

{
  "customerId": "1234567890",
  "birthday": {
    "day": 12,
    "month": 4,
    "year": 1992
  },
  "configId": "cfg_abc",
  "customerCurrency": "USD"
}

Parameters

Field	Description
customerId	Shopify Customer ID
birthday	Birthday object containing day, month and year
configId	Birthday reward configuration ID
customerCurrency	Customer's shopping currency

Response

{
  "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

POST /api/v1/merchant/social

https://dollarback-production.dollarlabs.io/api/v1/merchant/social

Request

{
  "customerId": "1234567890",
  "socialUrl": "https://instagram.com/yourshop",
  "configId": "cfg_social",
  "customerCurrency": "USD"
}

Parameters

Field	Description
customerId	Shopify Customer ID
socialUrl	Social profile URL being rewarded
configId	Social reward configuration ID
customerCurrency	Customer's shopping currency

Response

{
  "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.