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

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