Webshop Promotions

This set of APIs allows for the creation and activation of promotion codes associated with a specific promotion and organization. The APIs support generating and activating unique codes with expiration and redemption details.

POST/webshop-promotions/orders

Create activated promotion codes (order)

Creates an order of one or more products and returns an activated promotion code per ordered unit. If the customer (matched on e-mail address) does not exist yet, it is created automatically.

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

The canonical path is lowercase /webshop-promotions/orders. The legacy capitalised /Orders is accepted as an alias, but use lowercase in new integrations.

Required headers

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

Request body

Name
firstname
Type
string|Required
Description
The first name of the customer.
Name
lastname
Type
string|Required
Description
The last name of the customer.
Name
email
Type
string|Required
Description
The e-mail address of the customer. An existing customer with this address is reused.
Name
promotion_identifier
Type
string (uuid)|Required
Description
The UUID of the promotion (channel). Must belong to the organization and be active (between its start and end date).
Name
organization_identifier
Type
string|Required
Description
The identifier of the organization.
Name
off_peak_sale
Type
boolean|Required
Description
Must be a real JSON boolean (true/false) or 0/1. The strings "true"/"false" are rejected with a 422.
Name
products
Type
array|Required (min. 1)
Description
One element per product line. Each unit of quantity yields one activated code in the response.
Name
products[].product_id
Type
integer|Required
Description
The id of the product.
Name
products[].quantity
Type
integer|Required (min. 1)
Description
Number of units. One code is created per unit.
Name
products[].location_id
Type
integer|Required for pickup products
Description
The pickup location. Omit for delivery products.
Name
products[].variant_id
Type
integer|Optional
Description
Optional product variant.
Name
products[].value_id
Type
integer|Optional
Description
Optional variant value.
Name
shipping_address
Type
object|Required when the order contains a delivery product
Description
Required fields: first_name, last_name, address1, city, country, zip.

Error responses

401 — token missing/invalid or lacks the promotions.scan ability.
403 — Unauthorized organization (device does not belong to the organization) or Promotion not active.
404 — Organization not found, Device not found or Promotion not found or mismatched.
422 — validation failed: {"status": false, "message": "Validation failed", "errors": {"field": ["message"]}}. Product-level errors come as {"status": false, "errors": ["Product not found: ID 123"]}.

Request

POST

/webshop-promotions/orders

curl -X POST https://api.walletapp.co/webshop-promotions/orders \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer <your_token>" \
-d '{
    "firstname": "Jane",
    "lastname": "Doe",
    "email": "jane@example.com",
    "promotion_identifier": "<promotion_uuid>",
    "organization_identifier": "<organization_identifier>",
    "off_peak_sale": false,
    "products": [
        { "product_id": 3728, "quantity": 1, "location_id": 49 }
    ]
}'

Response

{
    "success": true,
    "message": "Promotion codes created",
    "shipping_address": null,
    "result": [
        {
            "code": "WLNT-XXXX-XXXX-XXXX",
            "expiration_date": "2026-11-10 12:00:00",
            "product_title": "Programma 1",
            "url": "https://channel.example.com/REF?promotion_code=WLNT-XXXX-XXXX-XXXX",
            "variant": null,
            "value": null
        }
    ]
}