Coupons

Coupons are a core concept for the Wallet App platform, Coupons are used as a 1 time use code that can be redeemed for a discount on a product or service in the real world. Coupons can be created and managed through the API.

The coupons model

The coupon model contains the information about a coupon. Such as the webshop pricing, when and for how long it should be active and the look and feel in the Apple or Android passwallet. The following properties are available:

Properties

Name
identifier
Type
string
Description
Unique identifier for the coupon.
Name
price
Type
float
Description
The sale price of the coupon.
Name
points
Type
integer
Description
The sale amount of points of the coupon.
Name
expiration_label
Type
string
Description
Label for the active, blocked, expired states of the coupon in the apple wallet.
Name
active_label
Type
string
Description
The text in the apple wallet for once a coupon is active.
Name
blocked_label
Type
string
Description
The text in the apple wallet for once a coupon is blocked.
Name
expired_label
Type
string
Description
The text shown in the apple wallet once a pass has expired.
Name
redeemed_label
Type
string
Description
The text shown in the apple wallet once a pass has been redeemed.
Name
show_title
Type
boolean
Description
whether or not to show the title in the apple wallet.
Name
show_subtitle
Type
boolean
Description
whether or not to show the subtitle in the apple wallet.
Name
organization
Type
object
Description
Contains in formation about the coupons organization. contains: ['identifier', 'name']
Name
primary_color
Type
string
Description
A Hexadecimal color code for the primary color of the coupon (background color for the apple wallet pass).
Name
text_color
Type
string
Description
A Hexadecimal color code for the text color of the coupon (text color for the apple wallet pass).
Name
label_color
Type
string
Description
A Hexadecimal color code for the label color of the coupon (label color for the apple wallet pass).
Name
title
Type
string
Description
The title of the coupon.
Name
subtitle
Type
string
Description
The subtitle of the coupon.
Name
thumbnail_url
Type
string|url
Description
The URL to the image of the coupon.
Name
start_date
Type
timestamp
Description
Used to set the availablity of the coupon in the webshop.
Name
end_date
Type
timestamp
Description
Used to set the availablity of the coupon in the webshop.
Name
use_start_and_end
Type
boolean
Description
whether or not to use a start and end date in the webshop.
Name
stock
Type
integer
Description
Amount of coupons available for sale or usage.
Name
use_stock
Type
boolean
Description
whether or not to use a stock in the webshop.
Name
created_at
Type
timestamp
Description
A timestamp when the coupon was created.
Name
updated_at
Type
timestamp
Description
A timestamp when the coupon was last updated.

Note

Because a user can have access to multiple organizations we require a organization_id to be provided for most requests. We will also return an organization reference in each response.

GET/coupons

List all coupons

This endpoint returns a list of all the coupons the currently authenticated user has access to.

Required headers

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

Abilities

Name
coupons.get
Type
string
Description
The scope required to access this endpoint.

Request

GET

/coupons

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

Response

{
"message": "Request successful",
"data": [
    {
        "active_label": "ongebruikt",
        "blocked_label": "geblokkeerd",
        "created_at": "<timestamp>",
        "end_date": "<timestamp>",
        "expiration_days": 30,
        "expiration_label": "Geldig t/m",
        "expired_label": "verlopen",
        "identifier": "<UUID>",
        "organization": {
            "name": "<organization_name>",
            "identifier": "<UUID>"
        },
        "points": 0,
        "price": 0,
        "primary_color": "#ffffff",
        "redeemed_label": "ingeleverd",
        "show_subtitle": 0,
        "show_title": 0,
        "start_date": "<timestamp>",
        "stock": 0,
        "subtitle": "<subtitle>",
        "text_color": "#000000",
        "thumbnail_url": "<url>",
        "title": "<title>",
        "updated_at": "2022-12-23T09:59:31.000000Z",
        "use_start_and_end": 0,
        "use_stock": 0
    },
],
...
}

POST/coupons

Create a coupon

This endpoint allows you to create a coupon.

Required headers

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

Abilities

Name
coupons.store
Type
string
Description
The scope required to access this endpoint.

Request body

Name
title
Type
string|Required
Description
The title of the coupon.
Name
subtitle
Type
string|Required
Description
The subtitle of the coupon.
Name
organization_id
Type
string|Required
Description
The organization id the coupon should be created for.
Name
description
Type
string
Description
The webshop description of a coupon.
Name
thumbnail_url
Type
string|url
Description
A valid url to the thumbnail image of a coupon.
Name
price
Type
float
Description
The webshop price of a coupon.
Name
external_reference
Type
string
Description
An external reference returned with each pass
Name
points
Type
integer
Description
The webshop amount of points for a coupon.
Name
expiration_label
Type
string
Description
The text shown in the apple wallet for the expiration date.
Name
expiration_days
Type
integer
Description
The amount of days the associated pass will be valid for after creation.
Name
blocked_label
Type
string
Description
The text in the apple wallet for once a coupon is blocked.
Name
expired_label
Type
string
Description
The text shown in the apple wallet once a pass has expired.
Name
active_label
Type
string
Description
The text shown in the apple wallet once a pass is active.
Name
redeemed_label
Type
string
Description
The text shown in the apple wallet once a pass has been redeemed.
Name
show_title
Type
boolean
Description
whether or not to show the title in the apple wallet.
Name
show_subtitle
Type
boolean
Description
whether or not to show the subtitle in the apple wallet.
Name
primary_color
Type
string
Description
A Hexadecimal color code for the primary color of the coupon (background color for the apple wallet pass).
Name
text_color
Type
string
Description
A Hexadecimal color code for the text color of the coupon (text color for the apple wallet pass).
Name
label_color
Type
string
Description
A Hexadecimal color code for the label color of the coupon (label color for the apple wallet pass).
Name
stock
Type
integer
Description
Amount of coupons available for sale or usage.
Name
use_stock
Type
boolean
Description
whether or not to use a stock in the webshop.
Name
start_date
Type
timestamp
Description
Used to set the availablity of the coupon in the webshop.
Name
end_date
Type
timestamp
Description
Used to set the availablity of the coupon in the webshop.
Name
use_start_and_end
Type
boolean
Description
whether or not to use a start and end date in the webshop.

Request

POST

/coupons

curl -X POST https://api.walletapp.co/coupons 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
    "title":"<your_title>",
    "subtitle":"<your_subtitle>",
    "description":"<your_description>",
    "organization_id":"<organization_id>",
    "thumbnail_url":"<image_url>",
    "price": 1.50,
    "expiration_label":"Pass status",
    "expiration_days": 22,
    "external_reference": "<string>",
    "expired_label":"Expired",
    "primary_color":"#ff00ff",
    "text_color":"#ff0000",
    "label_color":"#00ff00",
    "show_title": true,
    "show_subtitle": true,
    "active_label":"Active",
    "blocked_label":"Blocked",
    "redeemed_label":"Redeemed",
    "points": 12,
    "use_stock": true,
    "use_start_and_end": true,
    "stock":15,
    "start_date": "2022-01-01",
    "end_date":"2023-01-01"
}'

Response

{
"message": "Request successful",
"data": {
        "active_label": "ongebruikt",
        "blocked_label": "geblokkeerd",
        "created_at": "<timestamp>",
        "end_date": "<timestamp>",
        "expiration_days": 30,
        "expiration_label": "Geldig t/m",
        "expired_label": "verlopen",
        "identifier": "<UUID>",
        "organization": {
            "name": "<organization_name>",
            "identifier": "<UUID>"
        },
        "points": 0,
        "price": 0,
        "primary_color": "#ffffff",
        "redeemed_label": "ingeleverd",
        "show_subtitle": 0,
        "show_title": 0,
        "start_date": "<timestamp>",
        "stock": 0,
        "subtitle": "<subtitle>",
        "text_color": "#000000",
        "thumbnail_url": "<url>",
        "title": "<title>",
        "updated_at": "2022-12-23T09:59:31.000000Z",
        "use_start_and_end": 0,
        "use_stock": 0
    }
}

GET/coupons/:identifier

Inspect a coupon

The endpoint allows you to fetch a coupon by its identifier.

Required headers

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

Abilities

Name
coupons.get
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
identifier
Type
string
Description
The id of the coupon you want to update.

Request

GET

/coupons/:identifier

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

Response

{
"message": "Request successful",
"data": {
        "active_label": "ongebruikt",
        "blocked_label": "geblokkeerd",
        "created_at": "<timestamp>",
        "end_date": "<timestamp>",
        "expiration_days": 30,
        "expiration_label": "Geldig t/m",
        "expired_label": "verlopen",
        "identifier": "<UUID>",
        "organization": {
            "name": "<organization_name>",
            "identifier": "<UUID>"
        },
        "points": 0,
        "price": 0,
        "primary_color": "#ffffff",
        "redeemed_label": "ingeleverd",
        "show_subtitle": 0,
        "show_title": 0,
        "start_date": "<timestamp>",
        "stock": 0,
        "subtitle": "<subtitle>",
        "text_color": "#000000",
        "thumbnail_url": "<url>",
        "title": "<title>",
        "updated_at": "2022-12-23T09:59:31.000000Z",
        "use_start_and_end": 0,
        "use_stock": 0
    }
}

PUT/coupons/:identifier

Update a coupon

The endpoint allows you to modify a coupon

Required headers

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

Abilities

Name
coupons.update
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
identifier
Type
string
Description
The id of the coupon you want to update.

Request body

Name
title
Type
string
Description
The title of the coupon.
Name
subtitle
Type
string
Description
The subtitle of the coupon.
Name
organization_id
Type
string
Description
The organization id the coupon should be updated to.
Name
description
Type
string
Description
The webshop description of a coupon.
Name
thumbnail_url
Type
string|url
Description
A valid url to the thumbnail image of a coupon.
Name
price
Type
float
Description
The webshop price of a coupon.
Name
points
Type
integer
Description
The webshop amount of points for a coupon.
Name
expiration_label
Type
string
Description
The text shown in the apple wallet for the expiration date.
Name
expiration_days
Type
integer
Description
The amount of days the associated pass will be valid for after creation.
Name
blocked_label
Type
string
Description
The text in the apple wallet for once a coupon is blocked.
Name
expired_label
Type
string
Description
The text shown in the apple wallet once a pass has expired.
Name
active_label
Type
string
Description
The text shown in the apple wallet once a pass is active.
Name
redeemed_label
Type
string
Description
The text shown in the apple wallet once a pass has been redeemed.
Name
show_title
Type
boolean
Description
whether or not to show the title in the apple wallet.
Name
show_subtitle
Type
boolean
Description
whether or not to show the subtitle in the apple wallet.
Name
primary_color
Type
string
Description
A Hexadecimal color code for the primary color of the coupon (background color for the apple wallet pass).
Name
text_color
Type
string
Description
A Hexadecimal color code for the text color of the coupon (text color for the apple wallet pass).
Name
label_color
Type
string
Description
A Hexadecimal color code for the label color of the coupon (label color for the apple wallet pass).
Name
stock
Type
integer
Description
Amount of coupons available for sale or usage.
Name
use_stock
Type
boolean
Description
whether or not to use a stock in the webshop.
Name
start_date
Type
timestamp
Description
Used to set the availablity of the coupon in the webshop.
Name
end_date
Type
timestamp
Description
Used to set the availablity of the coupon in the webshop.
Name
use_start_and_end
Type
boolean
Description
whether or not to use a start and end date in the webshop.

Request

PUT

/coupons/:identifier

curl -X PUT https://api.walletapp.co/coupons/:identifier
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
    "title":"<your_title>",
    "subtitle":"<your_subtitle>",
    "description":"<your_description>",
    "organization_id":"<organization_id>",
    "thumbnail_url":"<image_url>",
    "price": 1.50,
    "expiration_label":"Pass status",
    "expiration_days": 22,
    "expired_label":"Expired",
    "primary_color":"#ff00ff",
    "text_color":"#ff0000",
    "label_color":"#00ff00",
    "show_title": true,
    "show_subtitle": true,
    "active_label":"Active",
    "blocked_label":"Blocked",
    "redeemed_label":"Redeemed",
    "points": 12,
    "use_stock": true,
    "use_start_and_end": true,
    "stock":15,
    "start_date": "2022-01-01",
    "end_date":"2023-01-01"
}'

Response

{
"message": "Request successful",
"data": {
        "active_label": "ongebruikt",
        "blocked_label": "geblokkeerd",
        "created_at": "<timestamp>",
        "end_date": "<timestamp>",
        "expiration_days": 30,
        "expiration_label": "Geldig t/m",
        "expired_label": "verlopen",
        "identifier": "<UUID>",
        "organization": {
            "name": "<organization_name>",
            "identifier": "<UUID>"
        },
        "points": 0,
        "price": 0,
        "primary_color": "#ffffff",
        "redeemed_label": "ingeleverd",
        "show_subtitle": 0,
        "show_title": 0,
        "start_date": "<timestamp>",
        "stock": 0,
        "subtitle": "<subtitle>",
        "text_color": "#000000",
        "thumbnail_url": "<url>",
        "title": "<title>",
        "updated_at": "2022-12-23T09:59:31.000000Z",
        "use_start_and_end": 0,
        "use_stock": 0
    }
}

DELETE/coupons/:identifier

Delete a coupon

The endpoint allows you to delete a coupon.

Required headers

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

Abilities

Name
coupons.delete
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
identifier
Type
string
Description
The id of the coupon you want to update.

Request

DELETE

/coupons/:identifier

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

Response

{
    "message": "Request successful",
    "data": "Coupon Archived",
}

PATCH/coupons/:identifier

Restore a coupon

The endpoint allows you to restore a coupon.

Required headers

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

Abilities

Name
coupons.delete
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
identifier
Type
string
Description
The id of the coupon you want to update.

Request

PATCH

/coupons/:identifier

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

Response

{
    "message": "Request successful",
    "data": "Coupon Restored",
}