- Platform Overview
- Resources and Guides
-
POS Integration
-
Getting Started
-
Core Concepts
-
Integration SDK
-
Certification
-
- Order Ahead
-
Provider Enablement
-
Provider Enablement
-
Endpoints
-
Developer Endpoints
-
-
API Reference
-
Getting Started
-
v15
-
- Access Tokens
- Campaigns
- Credit Cards
- Users
- Credit
- Locations
- Payment Methods
- QR Codes
- Progress Adjustments
- Orders
- Rewards
-
Gift Cards
- Add Value
- Create via Order
-
-
v14
-
- Credit
- Access Tokens
- Campaigns
- Categories
- Credit Cards
- Interstitials
- Locations
- Loyalty
- Orders
- Payment Tokens
- Support Tickets
- Users
-
-
Gift Cards .: Add Value
API Reference / v15
Add Gift Card Value
This endpoint adds Gift Card value given a QR code. The QR code can either be printed on a physical gift card or loaded directly onto a LevelUp user’s account using their QR code.
When integrating gift cards into a POS system, the gift card value should not be created until after the final tender event has occurred.
Note that the minimum amount that can be loaded on a gift card is $10.
Request Endpoint
Endpoint Idempotency
This endpoint is idempotent i.e. making the same request many times produces the same response as making it only once. This behavior avoids unwanted duplication in case of failures and/or retries; making it possible to safely retry sending the same gift card value addition many times. After a successful call, the transaction is executed and the addition created.
NOTE:
Each GUID can only create a single value addition. It is not possible to alter the value amount of a given value addition after it has been created.
Enabling Idempotency
To utilize the idempotency property of the endpoint, provide an external_identifier
in your requests. For subsequent retries, the same external_identifier
parameter of the first request must be used.
Authorization Required – Merchant Token in Header
Authorization: token 123456-75489120749...
Request Body
{
"gift_card_value_addition": {
"payment_token_data": "LU020000029080KFZ02I9A8V030000LU",
"value_amount": 1000,
"location_id": 1234,
"order_uuid": "a7e23820d56802321bb64ab3b58dfe6c",
"tender_types": ["cash"],
"type": "gift_card",
"identifier_from_merchant": "012345",
"external_identifier": "844f01e0-5802-4413-95aa-edc43b262de9"
}
}
Request Parameters
Param | Type | Required | Description |
---|---|---|---|
payment_token_data |
String | Yes | QR code data from gift card (input from the LevelUp Scanner). |
value_amount |
Integer | Yes | The amount (in cents) of value to be loaded onto the gift card (in cents) (Minimum $10). |
merchant_id |
Integer | Yes | The merchant ID of the merchant who is receiving the money for the gift card. |
location_id |
Integer | No | The location ID of the location that is receiving the money for the gift card. |
order_uuid |
String | No | The UUID of the LevelUp order (if the GC purchase transaction was tendered through LevelUp). |
tender_types |
Array | No | Array of strings of the type(s) of tender(s) used to purchase the gift card (levelup , cash , credit_card , gift_card , comp , house_account etc.). |
type |
String | No | The type of GC (typically gift_card for external integrations). |
identifier_from_ merchant
|
String | No | Ticket number from the POS. |
external_identifier |
String | No | The GUID of the transaction from the POS. |
cURL Example
curl -v https://sandbox.thelevelup.com/v15/merchants/34/gift_card_value_additions \
-H Accept:application/json \
-H Content-Type:application/json \
-H 'Authorization:token 982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73' \
-d '{
"gift_card_value_addition":{
"payment_token_data":"LU020000029080KFZ02I9A8V030000LU",
"value_amount": 1000,
"location_id": 19,
"order_uuid": "a7e23820d56802321bb64ab3b58dfe6c",
"tender_types": ["cash"],
"type": "gift_card",
"identifier_from_merchant": "012345",
"external_identifier": "844f01e0-5802-4413-95aa-edc43b262de9"
}
}'
Example Response
HTTP/1.1 200 OK
{
"gift_card_value_addition":
{
"added_value_amount": 1000,
"new_value_at_merchant_amount": 1000,
"old_value_at_merchant_amount": 0,
"uuid": "3f718140-aa1b-0136-f030-22fca54f06e4"
}
}
Response Parameters
Key | Type | Description |
---|---|---|
added_value_amount |
Integer | The value that was loaded onto the gift card |
new_value_ at_merchant_amount
|
Integer | The new total value available at that merchant |
old_value_ at_merchant_amount
|
Integer | The previous total value available at that merchant |
uuid |
String | The UUID for the gift card value addition |
Retry Request
A subsequent request was made with the same parameters (including the external_identifier
) as the example request but with a different value_amount
.
Request
curl -v https://sandbox.thelevelup.com/v15/merchants/34/gift_card_value_additions \
-H Accept:application/json \
-H Content-Type:application/json \
-H 'Authorization:token 982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73' \
-d '{
"gift_card_value_addition":{
"payment_token_data":"LU020000029080KFZ02I9A8V030000LU",
"value_amount": 3000,
"location_id": 19,
"order_uuid": "a7e23820d56802321bb64ab3b58dfe6c",
"tender_types": ["cash"],
"type": "gift_card",
"identifier_from_merchant": "012345",
"external_identifier": "844f01e0-5802-4413-95aa-edc43b262de9"
}
}'
Response
The authorized gift card value addition for the given external_identifier
had already been processed after the first example request. The response is identical to the first successful addition.
HTTP/1.1 200 OK
{
"gift_card_value_addition":
{
"added_value_amount": 1000,
"new_value_at_merchant_amount": 1000,
"old_value_at_merchant_amount": 0,
"uuid": "3f718140-aa1b-0136-f030-22fca54f06e4"
}
}
Errors
QR Code not found
HTTP/1.1 422 Unprocessable Entity
[
{
"error": {
"message": "You cannot add value to this QR code.",
"object": "gift_card_value_addition",
"property": "base"
}
}
]
Tried to load too much value
HTTP/1.1 422 Unprocessable Entity
[
{
"error": {
"object": "gift_cards/value_adder",
"property": "base",
"message": "Sorry, the maximum amount that you can add to a gift card at once is $500.00."
}
}
]
Tried to load 0 or negative value
HTTP/1.1 422 Unprocessable Entity
[
{
"error": {
"object": "gift_cards/value_adder",
"property": "base",
"message": "You must load a positive amount."
}
}
]
Not authorized to load for that merchant (bad merchant token)
HTTP/1.1 401 Unauthorized