Rewards .: List by Merchant

API Reference / v15

List a Users’s Rewards at a Particular Merchant

This endpoint returns a list of rewards available to a user. If no user token is provided, a list of rewards available to a new user will be shown.

Authorization Optional – User Token in Header or No Authorization

Authorization: token user=123456-75489120749...

Request Parameters

Param Type Required Description
lat Float No The latitude of the request area.
lng Float No The longitude of the request area.
transfer_supported Boolean No Indicates whether requester supports transferable rewards. If blank or false, no rewards that must be transfered will be shown.

Use of lat and lng is encouraged when the merchant has locations in multiple time zones, as this ensures that rewards with time windows are presented correctly.

Request

GET /v15/merchants/:merchant_id/rewards?transfer_supported=true

cURL Example with No Authentication

curl 'https://sandbox.thelevelup.com/v15/merchants/34/rewards?lat=42.405736&lng=-71.13081&transfer_supported=true' \
  -H Accept:application/json \
  -H Content-Type:application/json

cURL Example with User Authentication

curl 'https://sandbox.thelevelup.com/v15/merchants/34/rewards?lat=42.405736&lng=-71.13081&transfer_supported=true' \
  -H Accept:application/json \
  -H Content-Type:application/json \
  -H 'Authorization:token user="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"'

Response

HTTP/1.1 200 OK

[
  {
    "reward": {
      "id": "claim-123",
      "title": "$2 Birthday credit",
      "description": "Happy birthday! Expires in 12 days.",
      "earned": false,
      "created_at": "2015-05-01T12:33:41-04:00",
      "expires_at": "2015-06-01T12:33:41-04:00",
      "pausable": true,
      "paused": false,
      "source_campaign_id": 632,
      "tags": [],
      "transfer_required": false,
      "transferable": true,
      "usable": true,
      "usable_now": true,
      "usable_as_credit": true,
      "value_amount": 500,
      "value_remaining_amount": 200
    }
  }
]

Response Parameters

Param Type Description
id Integer The id of the reward.
title String The title of the reward.
description String The description of the reward.
earned Boolean State describing whether the reward is earned or not.
created_at Datetime ISO 8601 date and time (YYYY-MM-DDThh:mm:ss±hh:mm) when the reward was created.
expires_at Datetime ISO 8601 date and time (YYYY-MM-DDThh:mm:ss±hh:mm) when the reward expires. Null if no expiration.
pausable Boolean State describing if the reward is pausable or not.
paused Boolean The paused state of the reward. Paused rewards will not be redeemed automatically.
source_campaign_id Integer The campaign id for the reward (if applicable, otherwise null)
tags Array Array of merchant-defined tags for the campaign.
transfer_required Boolean State describing if the reward must be transfered to another user before it can be used.
transferable Boolean State describing if the reward is able to be transfered to another user.
usable Boolean State describing if the reward is usable or not.
usable_now   Boolean State describing if the reward is usable now or not (might be for a particular redemption time).
usable_as_credit Boolean State describing if the reward is usable as generic credit (might be an item-based campaign).
value_amount Integer Original reward value (in cents).
value_remaining_amount Integer The value remaining (in cents) of the reward (if applicable, otherwise null).