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.

The merchant_id param must be set in order to indicate which merchant this gift card can be used at.

If delayed gift cards is enabled, the sender will receive an email with instructions to confirm the purchase. 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 Yes LevelUp Merchant ID of merchant where the gift card can be used
recipient_email String Yes The email address of the gift card recipient
recipient_message String No The message that should be sent to the recipient along with the gift card
recipient_name String No 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,
    "delay_gift_card_migration": false
  }
}

Response Parameters

Key Type Description
added_value_amount Integer The value in cents that was loaded onto the gift card
delay_gift_card_migration Boolean Flag to indicate if delayed gift cards is enabled

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

Merchant not found

HTTP/1.1 422 Unprocessable Entity

[
  {
    "error": {
      "message": "You must specify a valid merchant.",
      "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