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.
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
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
},
],
...
}
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
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
}
}
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
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
}
}
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
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 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
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",
}
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
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",
}