Offers & Shops API

Offers and shops endpoints let you retrieve offer details and shop information for authenticated use cases.

• Authentication: All endpoints require a valid JWT Bearer token.

See JWT Authentication for token details.

Endpoints Overview

• GET /offer/shop/{shopId} – Get shop details
• GET /offer/{offerId} – Get offer details

GET /offer/shop/{shopId} – Get Shop Details

Retrieve a single shop by ID, with optional statistics.

• Method: GET
• Path: /v1/offer/shop/{shopId}
• Auth: Authorization: Bearer <JWT_TOKEN>

Path Parameters

Query Parameters

Response

• 200 OK

  {
    "shopId": "shop_123",
    "name": "Coffee Bar",
    "status": "ACTIVE",
    "logo": "https://example.com/logo.png",
    "image": "https://example.com/image.png",
    "description": {
      "de": "Beschreibung",
      "en": "Description"
    }
  }

  When includeStatistics=true, a statistics object may be included depending on configuration.

• 400 Bad Request

  • Invalid or missing shopId or shop type.

• 404 Not Found

  • Shop not found.

• 500 Internal Server Error

  • Error retrieving shop.

GET /offer/{offerId} – Get Offer Details

Retrieve a single offer by ID, with optional statistics and shop details.

• Method: GET
• Path: /v1/offer/{offerId}
• Auth: Authorization: Bearer <JWT_TOKEN>

Path Parameters

Query Parameters

Response

• 200 OK

  {
    "offer": {
      "offerId": "offer_123",
      "type": "LOCAL",
      "points": 100,
      "title": {
        "de": "Kostenloser Kaffee",
        "en": "Free Coffee"
      },
      "description": {
        "de": "Erhalte einen kostenlosen Kaffee",
        "en": "Get a free coffee"
      },
      "category": "FOOD",
      "shopId": "shop_123",
      "monthlyLimit": 50,
      "totalLimit": 500
    },
    "statistics": {
      /* monthly statistics for the offer when includeStatistics=true */
    },
    "totalStatistics": {
      /* aggregated lifetime statistics for the offer (redeemed, valid, limit, …) */
    },
    "shop": {
      /* embedded shop object when includeShop=true */
    }
  }

• 400 Bad Request

  • Invalid offerId or unsupported id format.

• 404 Not Found

  • Offer not found.

• 500 Internal Server Error

  • Error retrieving offer or statistics.