Promotions

Promotions codes are a core concept for the Wallet App platform, codes are used as a one time use code that can be redeemed for free service in the real world. Codes can be created and managed through the API.

POST/promotions/requestActivatedCode

Create a promotions code

The coupon model is related to generated a new promotions and activate code for specific user.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Request body

Name
promotion_id
Type
integer
Description
The promotion id it belongs to the promotion
Name
location_id
Type
integer
Description
The location id it belongs to the location
Name
activation_date
Type
string
Description
The code activation date
Name
first_name
Type
string
Description
The first name for create as user
Name
last_name
Type
string
Description
The last name for create as user
Name
email
Type
string
Description
The email used for communication purposes

Request

POST

/promotions/requestActivatedCode

curl -X POST https://api.walletapp.co/promotions/requestActivatedCode 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
    "promotion_id":"<uuid>",
    "location_id":"<identifier>",
    "activation_date":"<activation_date>",
    "first_name":"<first_name>",
    "last_name":"<last_name>",
    "email":"<email>",
}'

Response

{
    "message": "Promotion code activated successfully",
    "data": {
        "code": "<code>",
        "expiration_date": "<expiration_date>",
        "first_name": "<first_name>",
        "last_name": "<last_name>",
        "email": "<email>",
        "url": "<url>"


    }
}

GET/promotions/requestUnactivatedCode/:identifier

All redeemed a code list

The endpoint allows you to fetch a promotion codes by its identifier.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Route parameters

Name
identifier
Type
string
Description
The id of the promotion you want to fetch data for.

Request

GET

/promotions/requestUnactivatedCode/:identifier

curl -X GET https://api.walletapp.co/promotions/requestUnactivatedCode/:identifier
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

{
    "message": "Redeemed Codes fetched successfully",
    "result": {
        "data": "[<Code List>]"
    }
}

GET/promotion/getBrandsList

Get brands list as per promotion

The endpoint allows you to fetch a brands list as promotions by its promotion_id.

Required headers

This API requires a Device Token. These tokens are generated in the dashboard by navigating to "Scanners" and clicking the key icon.

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Request body

Name
organization_identifier
Type
string
Description
The organization identifier it's belongs to promotion
Name
promotion_identifier
Type
string
Description
The promotion identifier it's belongs to promotion

Request

GET

/promotion/getBrandsList

curl -X GET https://api.walletapp.co/promotion/getBrandsList
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
    "organization_identifier":"<organization_identifier>",
    "promotion_identifier":"<promotion_identifier>"
}'

Response

{
  "success": true,
  "message": "Data fetch successfully",
  "data": {
      "id": <promotion_id>,
      "organization_id": <organization_id>,
      "title": <title>,
      "reference": <reference>,
      "description":<description>,
      "start_date":<start_date>,
      "end_date":<end_date>,
      "brands": [
          <brands list>
          "locations": [
              <locations list>
               "locationTime": {
                  <locationTime>
               },
               "locationLabels": {
                  <locationLabels> 
              }
              "products": {
                  <products> 
              }
          ]
      ],
      "pivot": {
          "promotion_id": <promotion_id>,
          "brand_id": <brand_id>,
          "description": <description>,
          "link": <link>,
          "premium": <premium>
      }

  }
}

Get delivery products `GET /promotion/getDeliveryProducts`

This endpoint returns only delivery-type products linked to valid locations and brands for a given promotion, filtered by allowed categories associated with the device.

Ensures the device and organization are authorized.
Filters out locations excluded by promotion limits or exceptions.
Loads locationTime, locationLabels, and complete product info.
Prepends full image URLs to products and location images.
Excludes locations that do not match category constraints or have no valid delivery products.

Required headers

Name
Authorization
Type
string
Description
Bearer token of the authenticated device.

Request body

Name
organization_identifier
Type
string
Description
Identifier of the organization.
Name
promotion_identifier
Type
string
Description
UUID of the promotion.

Request

GET

/promotion/getDeliveryProducts

curl -X GET https://api.walletapp.co/promotion/getDeliveryProducts \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_identifier": "org-123",
    "promotion_identifier": "promo-uuid"
  }'

{
  "success": true,
  "message": "Data fetch successfully",
  "data": {
    "id": 12,
    "title": "Spring Promo",
    "reference": "spring-2025",
    "start_date": "2025-05-01",
    "end_date": "2025-07-31",
    "brands": [
      {
        "id": 5,
        "name": "CarWash Brand",
        "locations": [
          {
            "id": 101,
            "title": "Main Street Location",
            "image": "https://content.walletapp.co/storage/locations/img101.jpg",
            "locationTime": {
              "monday_open": "08:00",
              "monday_close": "18:00"
            },
            "locationLabels": [
              {
                "label": "Open 24/7",
                "color": "#00ff00"
              }
            ],
            "products": [
              {
                "id": 928,
                "title": "Premium Wash",
                "type": "pickup",
                "price": "200.00",
                "thumbnail_url": "https://content.walletapp.co/storage/products/img928.png",
                "description": "<p>Includes underbody and polish</p>",
                "category": {
                  "id": 2,
                  "name": "Exterior"
                },
                "subcategory": {
                  "id": 5,
                  "name": "Deluxe"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

GET/promotion/getLocations

Get locations with valid products

Returns a paginated list of locations that have at least one valid product linked in allowed categories for the device.

Required headers

Name
Authorization
Type
string
Description
Bearer token of the authenticated device.

Query parameters

Name
organization_identifier
Type
string
Description
Identifier of the organization the device is tied to.
Name
promotion_identifier
Type
string
Description
Identifier (UUID) of the promotion.
Name
page
Type
integer
Description
Page number (optional, default is 1).
Name
per_page
Type
integer
Description
Number of results per page (optional, default is 10).

Request

GET

/promotion/getLocations

curl -X GET "https://api.walletapp.co/promotion/getLocations?organization_identifier=org-123&promotion_identifier=promo-uuid&page=1&per_page=10" \
-H "Authorization: Bearer <your_token>"

Response

{
  "success": true,
  "message": "Locations fetched successfully",
  "data": [
    {
      "id": 123,
      "title": "Location A",
      "latitude": "52.3676",
      "longitude": "4.9041",
      "address": "Street 1, City",
      "slug": "location-a",
      "image": "https://.../storage/path.jpg"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 1,
    "last_page": 1
  }
}

GET/promotion/getLocations/{identifier}

Get location details

Returns all location metadata (excluding products), such as opening hours and labels, for a specific location.

Required headers

Name
Authorization
Type
string
Description
Bearer token of the authenticated device.

Path parameter

Name
identifier
Type
integer
Description
Location ID.

Query parameters

Name
organization_identifier
Type
string
Description
Identifier of the organization.
Name
promotion_identifier
Type
string
Description
Identifier (UUID) of the promotion.

Request

GET

/promotion/getLocations/{identifier}

curl -X GET "https://api.walletapp.co/promotion/getLocations/123?organization_identifier=org-123&promotion_identifier=promo-uuid" \
-H "Authorization: Bearer <your_token>"

Response

{
  "success": true,
  "location": {
    "id": 123,
    "title": "Location A",
    "address": "Main Street 123",
    "latitude": "52.3676",
    "longitude": "4.9041",
    "slug": "location-a",
    "image": "https://.../storage/path.jpg",
    "locationTime": {
      "monday_open": "08:00",
      "monday_close": "18:00"
      // etc.
    },
    "locationLabels": [
      // ...
    ]
  }
}

GET/promotion/getLocations/{identifier}/products

Get products at a location

Returns the products linked to a specific location, filtered by allowed categories and promotion constraints.

Required headers

Name
Authorization
Type
string
Description
Bearer token of the authenticated device.

Path parameter

Name
identifier
Type
integer
Description
Location ID.

Query parameters

Name
organization_identifier
Type
string
Description
Identifier of the organization.
Name
promotion_identifier
Type
string
Description
Identifier (UUID) of the promotion.

Request

GET

/promotion/getLocations/{identifier}/products

curl -X GET "https://api.walletapp.co/promotion/getLocations/123/products?organization_identifier=org-123&promotion_identifier=promo-uuid" \
-H "Authorization: Bearer <your_token>"

Response

{
  "status": true,
  "products": [
    {
      "id": 928,
      "title": "Test Product",
      "type": "pickup",
      "price": "200.00",
      "thumbnail_url": "products/thumbnails/img.png"
    }
  ]
}

POST/promotion/activate-code

Create and activate a promotion code

Generates and activates a promotion code for a customer, based on device token, promotion ID, and organization.

Required headers

Name
Authorization
Type
string
Description
Bearer token of the authenticated device.

Request body

Name
customer_identifier
Type
string
Description
Unique external identifier of the customer (e.g. loyalty ID).
Name
organization_identifier
Type
string
Description
Identifier of the organization.
Name
promotion_identifier
Type
string
Description
UUID of the promotion.
Name
location_id
Type
integer
Description
ID of the location where the promotion is redeemed.
Name
product_id
Type
integer
Description
Product associated with the promotion code (required if off_peak_sale is true).
Name
off_peak_sale
Type
boolean
Description
Whether the code is for an off-peak sale.

Behavior

Authenticates the device via bearer token.
Verifies organization and promotion validity.
Ensures promotion is currently active.
Optionally links the code to a product and location.
Generates a unique WLNT code.
Resolves a custom scan reference if configured via device_promotion.
Returns a redeem URL and QR code image URL.

Request

POST

/promotion/activate-code

curl -X POST "https://api.walletapp.co/promotion/activate-code" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_identifier": "cust-xyz",
    "organization_identifier": "org-123",
    "promotion_identifier": "promo-uuid",
    "location_id": 123,
    "product_id": 456,
    "off_peak_sale": false
  }'

POST/promotion/activate-promo

Activate a promotion code via API

Creates and activates a promotion code via the scanner API. This endpoint is designed for devices/scanners to generate promotion codes programmatically with automatic limit tracking.

Required headers

This API requires a Device Token (Sanctum token). These tokens are generated in the dashboard by navigating to "Scanners" and clicking the key icon.

Name
Authorization
Type
string
Description
Bearer token of the authenticated device.

Request body

Name
organization_identifier
Type
string
Description
Identifier of the organization the promotion belongs to.
Name
promotion_identifier
Type
string
Description
UUID of the promotion to create a code for.

Behavior

Authenticates the device via bearer token
Checks if the device has reached its API code generation limit
Verifies the device belongs to the specified organization
Validates the promotion is currently active (between start and end dates)
Generates a unique WLNT promotion code
Sets expiration date based on device configuration (default: 365 days)
Stores custom API pricing if configured on the device
Increments the device's API codes used counter
Returns the code, expiration date, promotion URL, and remaining limit

Response fields

code: The generated promotion code (format: WLNT-XXXXXXXXXXXXX)
expiration_date: When the code expires (YYYY-MM-DD HH:MM:SS)
url: The promotion landing page URL
limit: Remaining codes available in "used/total" format (null if no limit)
api_codes_used: Current number of codes used
api_code_limit: Total limit (null if unlimited)

Request

POST

/promotion/activate-promo

curl -X POST "https://api.walletapp.co/promotion/activate-promo" \
  -H "Authorization: Bearer <device_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_identifier": "org-123",
    "promotion_identifier": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

{
  "success": true,
  "message": "Promotion code created successfully",
  "data": {
    "code": "WLNT-ABC123XYZ9Z9W",
    "expiration_date": "2026-11-20 14:22:33",
    "url": "https://promo.example.com/spring-sale",
    "limit": "245/250",
    "api_codes_used": 5,
    "api_code_limit": 250
  }
}

Error - Limit Reached

{
  "status": false,
  "message": "API code limit reached",
  "limit": 250,
  "used": 250
}

Error - Promotion Inactive

{
  "status": false,
  "message": "Promotion not active"
}

POST/promotion/block-promo

Block a promotion code

Blocks a previously generated promotion code that hasn't been assigned to a user or redeemed. This endpoint decrements the device's API codes used counter, freeing up capacity for new codes.

Required headers

This API requires a Device Token (Sanctum token). These tokens are generated in the dashboard by navigating to "Scanners" and clicking the key icon.

Name
Authorization
Type
string
Description
Bearer token of the authenticated device.

Request body

Name
organization_identifier
Type
string
Description
Identifier of the organization the promotion belongs to.
Name
promotion_identifier
Type
string
Description
UUID of the promotion.
Name
code
Type
string
Description
The promotion code to block (e.g., WLNT-ABC123XYZ9Z9W).

Behavior

Authenticates the device via bearer token
Verifies the device belongs to the specified organization
Validates the promotion exists
Checks if the code exists for this promotion
Prevents blocking if the code is already assigned to a user
Prevents blocking if the code has been redeemed
Prevents blocking if the code is already blocked
Marks the code as blocked with a timestamp
Decrements the device's API codes used counter
Returns the updated limit status

Response fields

code: The blocked promotion code
limit: Remaining codes available in "used/total" format (null if no limit)
api_codes_used: Current number of codes used (after decrement)
api_code_limit: Total limit (null if unlimited)

Request

POST

/promotion/block-promo

curl -X POST "https://api.walletapp.co/promotion/block-promo" \
  -H "Authorization: Bearer <device_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_identifier": "org-123",
    "promotion_identifier": "550e8400-e29b-41d4-a716-446655440000",
    "code": "WLNT-ABC123XYZ9Z9W"
  }'

Response - Success

{
  "success": true,
  "message": "Promotion code blocked",
  "data": {
    "code": "WLNT-ABC123XYZ9Z9W",
    "limit": "246/250",
    "api_codes_used": 4,
    "api_code_limit": 250
  }
}

Error - Already Assigned

{
  "success": false,
  "message": "Code cannot be blocked - already assigned to a user",
  "data": {
    "code": "WLNT-ABC123XYZ9Z9W",
    "limit": "245/250"
  }
}

Error - Already Redeemed

{
  "success": false,
  "message": "Code already redeemed",
  "data": {
    "code": "WLNT-ABC123XYZ9Z9W",
    "limit": "245/250"
  }
}

Error - Already Blocked

{
  "success": false,
  "message": "Code already blocked",
  "data": {
    "code": "WLNT-ABC123XYZ9Z9W",
    "limit": "245/250"
  }
}