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/promotions/requestActivatedCode

Create and activate a promotion code

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.

Behavior

Verify the device's token and associated location.
Ensure the device's brand is part of the specified organization.
Validate that the promotion exists and is currently active.
Fetch products linked to the specified location, restricted to:
- Categories allowed for that location-device.
- Products that are part of the promotion or allowed under current rules.

Request

POST

/promotions/requestActivatedCode

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

Response

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