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

POST /v15/merchants/:merchant_id/gift_card_value_additions

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"
  }
}

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.

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"
    }
  }'

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
    }
}

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

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