> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Reward Integration & Delivery

> Complete guide to integrating Nudj rewards with external wallets, loyalty systems, and custom fulfillment platforms

When users earn rewards in Nudj, they expect those rewards to appear in their existing wallets and loyalty systems. This guide covers how to connect Nudj's reward system with your external infrastructure for seamless reward delivery.

<Info>
  **Quick Decision**: Have an existing loyalty system? Use **API Integration**. Need real-time notifications? Use **Webhooks**. Building something custom? Use **Direct Integration**.
</Info>

## Reward Delivery Methods

<CardGroup cols={2}>
  <Card title="Webhook Integration" icon="webhook" color="#0ea5e9">
    **Best for**: Real-time notifications, event-driven systems

    **Pros**: Instant delivery, reliable processing, automatic retries

    **Cons**: Requires endpoint setup, security considerations
  </Card>

  <Card title="API Integration" icon="code" color="#10b981">
    **Best for**: Existing loyalty systems, scheduled processing

    **Pros**: Full control, batch processing, error handling

    **Cons**: Polling required, potential delays
  </Card>

  <Card title="Direct Integration" icon="plug" color="#f59e0b">
    **Best for**: Custom systems, specialized requirements

    **Pros**: Maximum flexibility, custom logic, deep integration

    **Cons**: Complex setup, maintenance overhead
  </Card>

  <Card title="Shopify-Backed Rewards" icon="shopify" color="#96BF47" href="/enterprise/shopify/rewards">
    **Best for**: Shopify storefronts

    Discount codes, free-product-via-discount-function redemptions, checkout-link redemptions, and product sync from Shopify into the Nudj reward catalog. See [Shopify Rewards](/enterprise/shopify/rewards).
  </Card>
</CardGroup>

## Understanding Nudj Rewards

<Tabs>
  <Tab title="Reward Types">
    **Two main categories of rewards in Nudj**:

    <AccordionGroup>
      <Accordion title="Assets (Guaranteed Rewards)">
        **Direct rewards that users receive immediately**:

        * **Points/Currency**: Loyalty points, credits, tokens
        * **Digital Items**: Coupons, discount codes, digital content
        * **Physical Items**: Merchandise, gift cards (requires fulfillment)
        * **Access Rights**: Premium features, exclusive content

        ```json theme={null}
        {
          "type": "asset",
          "reward": {
            "id": "reward_123",
            "name": "10% Discount Code",
            "type": "digital_coupon",
            "value": "SAVE10",
            "description": "10% off your next purchase"
          }
        }
        ```
      </Accordion>

      <Accordion title="Entries (Chance-Based Rewards)">
        **Competition entries that give users chances to win**:

        * **Prize Draws**: Monthly competitions, grand prizes
        * **Instant Win**: Scratch cards, spin-to-win mechanics
        * **Tiered Competitions**: Multiple prize levels
        * **Limited Availability**: First-come-first-served rewards

        ```json theme={null}
        {
          "type": "entry",
          "reward": {
            "id": "entry_456",
            "name": "Monthly Prize Draw Entry",
            "competition_id": "comp_789",
            "draw_date": "2024-03-01T00:00:00Z",
            "prize_description": "£500 Shopping Voucher"
          }
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Webhook Integration

Real-time reward delivery using webhooks for immediate processing when users earn rewards.

### Implementation Guide

<Steps>
  <Step title="Set Up Webhook Endpoint">
    Create a secure endpoint to receive reward notifications:

    ```javascript theme={null}
    app.post('/webhooks/nudj/rewards', (req, res) => {
      // Verify webhook signature
      const signature = req.headers['x-nudj-signature'];
      if (!verifySignature(req.body, signature)) {
        return res.status(401).json({ error: 'Invalid signature' });
      }
      
      // Process reward
      processReward(req.body)
        .then(() => res.status(200).json({ success: true }))
        .catch(error => res.status(500).json({ error: 'Processing failed' }));
    });
    ```
  </Step>

  <Step title="Configure Webhook in Nudj">
    Set up the webhook configuration in your Nudj admin panel:

    ```json theme={null}
    {
      "webhook_config": {
        "url": "https://your-api.com/webhooks/nudj/rewards",
        "events": [
          "reward.earned",
          "reward.delivered",
          "reward.failed"
        ],
        "authentication": {
          "type": "hmac_sha256",
          "secret": "your-webhook-secret"
        }
      }
    }
    ```
  </Step>
</Steps>

### Real-World Integration Examples

<Tabs>
  <Tab title="Mobile App Wallet (Tesco-style)">
    **Integration with mobile app loyalty systems**:

    ```javascript theme={null}
    async function handleMobileWalletDelivery(user, reward) {
      // Add points to mobile wallet
      const walletResult = await mobileWalletAPI.creditAccount({
        customer_id: user.external_id,
        amount: reward.value,
        currency: reward.currency,
        transaction_type: 'engagement_reward'
      });
      
      // Trigger push notification
      await pushNotificationService.send({
        device_tokens: user.device_tokens,
        notification: {
          title: 'Reward Earned!',
          body: `${reward.value} points added to your wallet`
        }
      });
    }
    ```
  </Tab>

  <Tab title="E-commerce Loyalty Integration">
    **Integration with e-commerce platforms and existing loyalty systems**:

    ```javascript theme={null}
    async function handleEcommerceLoyalty(user, reward) {
      // Add to loyalty program
      const loyaltyResult = await ecommerceAPI.loyalty.addPoints({
        customer_email: user.email,
        points: reward.value,
        program_tier: await getTierForUser(user.external_id)
      });
      
      // Create personalized discount if threshold reached
      if (loyaltyResult.points_total >= loyaltyResult.next_reward_threshold) {
        const discount = await createPersonalizedDiscount(user, loyaltyResult);
        await emailService.send({
          to: user.email,
          template: 'milestone_reward',
          data: { discount_code: discount.code }
        });
      }
    }
    ```
  </Tab>
</Tabs>

## API Integration

Pull-based integration where your system periodically retrieves earned rewards from Nudj APIs.

### Implementation Guide

<Steps>
  <Step title="Set Up API Credentials">
    Configure API access for retrieving rewards:

    ```bash theme={null}
    NUDJ_API_BASE_URL=https://your-company.nudj.cx/api
    NUDJ_API_TOKEN=your-api-token
    ```
  </Step>

  <Step title="Implement Reward Polling">
    Create a service to regularly check for new rewards:

    ```javascript theme={null}
    async function pollForRewards() {
      const response = await this.apiClient.get('/rewards/pending', {
        params: {
          since: this.lastProcessedTimestamp,
          limit: 100,
          status: 'pending_delivery'
        }
      });
      
      const rewards = response.data.rewards;
      console.log(`Found ${rewards.length} pending rewards`);
      
      for (const reward of rewards) {
        await this.processReward(reward);
      }
    }
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={3}>
  <Card title="→ Webhook Setup Guide" icon="webhook" href="/enterprise/webhook-rewards">
    **Deep Dive**: Detailed webhook configuration and event handling
  </Card>

  <Card title="→ Authentication Integration" icon="key" href="/enterprise/oauth-authentication">
    **Prerequisites**: Set up user authentication before reward delivery
  </Card>

  <Card title="→ Webhook Events Catalog" icon="list" href="/enterprise/webhooks-events-catalog">
    **Reference**: Full list of webhook event types emitted by Nudj.
  </Card>
</CardGroup>