Gift Cards .: Create via Order

API Reference / v15

Create, Pay for and Send a Digital Gift Card via Email

This endpoint creates a gift card and charges the paying user for the card. The gift card can be sent to another user via email address or claimed for the paying user by specifying their own email.

This gift card can either be merchant specific (by including the merchant_id param) or for all merchants in the LevelUp ecosystem (by omitting the merchant_id param).

Once approved, both the recipient and sender will receive an email with instructions or confirmation.

Note that the minimum amount that can be loaded on a gift card is $10.

Request Endpoint

POST /v15/users/gift_card_value_orders

Authorization Required – User Token in Header

Authorization: token user="123456-75489120749..."

Request Body

{
  "gift_card_value_order": {
    "merchant_id": 1234,
    "recipient_email": "recipientemail@example.com",
    "recipient_message": "You just got a gift card",
    "recipient_name": "RecipientName",
    "value_amount": 1000
  }
}

Request Parameters

Param Type Required Description
merchant_id Integer No LevelUp Merchant ID of merchant where the gift card can be used (if specified - if omitted, gift card can be used at any merchant)
recipient_email String Yes The email address of the gift card recipient
recipient_message String Yes The message that should be sent to the recipient along with the gift card
recipient_name String Yes The recipient’s name
value_amount Integer Yes The amount (in cents) that should be loaded on the gift card (minimum 1000)

cURL Example

curl -v https://sandbox.thelevelup.com/v15/users/gift_card_value_orders \
  -H Accept:application/json \
  -H Content-Type:application/json \
  -H 'Authorization:token user="982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73"' \
  -d '{
        "gift_card_value_order": {
          "merchant_id": 1234,
          "recipient_email": "recipientemail@example.com",
          "recipient_message": "You just got a gift card",
          "recipient_name": "RecipientName",
          "value_amount": 1000
        }
      }'

Example Response

HTTP/1.1 200 OK

{
  "gift_card_value_order": {
    "added_value_amount":1000
  }
}

Response Parameters

Key Type Description
added_value_amount Integer The value in cents that was loaded onto the gift card

Errors

QR Code not found

HTTP/1.1 422 Unprocessable Entity

[
  {
      "error": {
          "message": "The email address you entered is invalid. Please retry with a valid email.",
          "object": "gift_card_value_order",
          "property": "base"
      }
  }
]

Tried to load too much value

HTTP/1.1 422 Unprocessable Entity

[
  {
      "error": {
          "message": "The minimum amount you can load at once is $10.00.",
          "object": "gift_card_value_order",
          "property": "base"
      }
  }
]

Tried to load 0 or negative value

HTTP/1.1 422 Unprocessable Entity

[
  {
    "error": {
      "object": "gift_card_value_order",
      "property": "base",
      "message": "You must load a positive amount."
    }
  }
]

Not authorized to load for that user (bad user token)

HTTP/1.1 401 Unauthorized