NAV
cURL

API Overview

This API provides Instagift merchants and consumers the ability to read and interact with select Instagift data. It is exposed as an HTTP API, so that it can be used from any language. It accepts and returns JSON only, and closely follows the format of JSON API.

Authentication

Sample request including user authentication headers

curl https://api.instagift.com/v2/sample/endpoint \
  -H "X-User-Email: person@example.com" \
  -H "X-User-Token: quhZKsGMSJc5eUAYm-FA" \

Sample request including merchant authentication headers

curl https://api.instagift.com/v2/sample/endpoint \
  -H "X-Merchant-Key: OWqqv2rwnWucQC22CVwvMg" \
  -H "X-Merhcant-Secret: 1WngOCryMpl1l7fXH7DIYA"

Both User and Merchant accounts of Instagift can authenticate by setting a combination of two HTTP request headers (‘X-User-Email’ and ‘X-User-Token’ for users and ‘X-Merchant-Key’ and ‘X-Merchant-Secret’ for merchants). Throughout this doc, endpoints and query filters will be marked as USER, MERCHANT, or PUBLIC depending on the type of authorization required.

Note: Throughout this doc, cURL examples will not include sample authentication headers.

User Authentication HTTP Headers

Parameter Required Description
X-User-Email true A valid email for an Instagift user account
X-User-Token true See Request User Token

Merchant Authentication HTTP Headers

Parameter Required Description
X-Merchant-Key true Generated from the Merchant Dashboard
X-Merchant-Secret true Generated from the Merchant Dashboard

Support

Please email support@instagift.com with all questions and issues.

Additionally, the source for this guide is publicy available on GitHub. Feel free to submit pull requests if you find any typos or missing data, we’ll do our best to keep it updated.

Rate Limiting

Coming soon

Table of Contents

Public Endpoints

The following API endpoints are accessible without user or merchant authentication.

Endpoint Description
GET /v2/locations/{locations.id} Fetch a Location
GET /v2/merchants/{merchants.id}/locations List all Locations for a Merchant
GET /v2/products/{products.id}/locations List all Redemption Locations for a Product
GET /v2/merchants/{merchants.id} Fetch a Merchant
POST /v2/passwords Reset User Password
GET /v2/products/{products.id} Fetch a Product
GET /v2/product_options/{product_options.id} Fetch a Product Option
GET /v2/products/{products.id}/product_options List all Product Options for a Product
POST /v2/support_tickets Create a Support Ticket
POST /v2/users Create a User
POST /v2/tokens Request User Token

User Endpoints

The following API endpoints are accessible with valid user authentication, see Request User Token.

Endpoint Description
GET /v2/certificates/{certificates.id} Fetch a Certificate
GET /v2/certificates List all Certificates
POST /v2/certificates/{certificates.id}/certificates Split a Certificate
POST /v2/certficates/{certificates.id}/redemptions Redeem a Certificate
POST /v2/certificates/{certificates.id}/gifts Gift a Certificate
PUT /v2/certificates/{certificates.claim_code} Claim a Certificate by Claim Code
GET /v2/gifts/{gifts.id} Fetch a Gift
GET /v2/gifts List all Gifts
GET /v2/redemptions/{redemptions.id} Fetch a Redemption
GET /v2/redemptions List all Redemptions
GET /v2/users/{users.id} Fetch a User
DELETE /v2/tokens Reset Token

Merchant Endpoints

The following API endpoints are accessible with valid merchant authentication. Merchant’s can generate API keys from their Instagift Merchant Dashboard. GROW plan required

Endpoint Description
GET /v2/certificates/{certificates.id} Fetch a Certificate
GET /v2/certificates List all Certificates
POST /v2/certificates/{certificates.id}/redemptions Redeem a Certificate
GET /v2/claim_codes/{certificates.claim_code} Fetch a Certificate by Claim Code
POST /v2/claim_codes/{certificates.claim_code}/redemptions Redeem a Certificate by Claim Code
GET /v2/redemptions/{redemptions.id} Fetch a Redemption
GET /v2/redemptions List all Redemptions
GET /v2/users Fetch a User

Ecommerce

The following merchant authenticated endpoints should be used when integrating an ecommerce site with Instagift gift card redemptions.

Endpoint Description
GET /v2/claim_codes/{certificates.claim_code} Fetch a Certificate by Claim Code
POST /v2/claim_codes/{certificates.claim_code}/redemptions Redeem a Certificate by Claim Code

Please see the Ecommerce Integration section for more detailed instructions.

Certificates

Fetch a Certificate

Sample request

curl https://api.instagift.com/v2/certificates/AzoXEYPYxG3OUaKJi234WQ

Sample response

{
    "links": {
        "certificates.user": "/v2/users/{certificates.user}",
        "certificates.parent": "/v2/certificates/{certificates.parent}",
        "certificates.merchant": "/v2/merchants/{certificates.merchant}",
        "certificates.product": "/v2/merchants/{certificates.product}"
    },
    "certificates": [
        {
            "id": "hD65TJvxnv8oIuyOmD056w",
            "href": "/v2/certificates/hD65TJvxnv8oIuyOmD056w",
            "product_type": "GiftCertificate",
            "claim_code": "62DD-CV4T-R2NTM2",
            "merchant_code": "R2NTM2",
            "status": "assigned",
            "marked_as_printed": false,
            "can_split_value": true,
            "qrcode_image": "/system/qrcodes/hD65TJvxnv8oIuyOmD056w.png",
            "currency": "USD",
            "face_value_cents": 10000,
            "price_cents": 10000,
            "product_redemption_locations_count": 1,
            "product_is_print_only": false,
            "product_is_giveaway": false,
            "product_seller_name": "Tuscan Kitchen",
            "product_merchant_name": "Tuscan Kitchen",
            "product_title": "$100 Tuscan Kitchen eGift Card",
            "thumb": null,
            "merchant": {
                "id": "_P07R17NtAZhxN56rneT7A",
                "href": "/v2/merchants/_P07R17NtAZhxN56rneT7A",
                "url": "http://tuscankitchen.instagift.com/",
                "name": "Tuscan Kitchen",
                "time_zone": "Eastern Time (US & Canada)",
                "logo": "/logos/original/missing.png",
                "locations": [
                    {
                        "id": "108esJv3En11Ugc6VZLyCA",
                        "href": "/v2/locations/108esJv3En11Ugc6VZLyCA",
                        "display": "Tuscan Kitchen, 100 Main St., Ste 2, Pleasantville, KS",
                        "name": "Tuscan Kitchen",
                        "address1": "100 Main St.",
                        "address2": "Ste 2",
                        "city": "Pleasantville",
                        "state": "KS",
                        "zip": "67502",
                        "phone": "3166620036",
                        "lat": null,
                        "lng": null
                    }
                ]
            },
            "daily_deal_store": null,
            "product": {
                "id": "NnjAQSTtcMcHYZXhRehPVQ",
                "href": "http://tuscankitchen.instagift.com/gift-card",
                "type": "GiftCertificate",
                "discount_sale_name": null,
                "is_giveaway": false,
                "can_split_value": true,
                "gift_card_image": null,
                "photos": [],
                "headline": null,
                "tagline": "Tuscan Kitchen eGift Card",
                "terms": [
                    "Good on any food or drink",
                    "Can be used on tax and gratuity",
                    "Does not expire",
                    "Merchant are not required to give change for the unused balance"
                ],
                "expiration_instructions": "Unless otherwise noted, this gift card NEVER EXPIRES",
                "redemption_instructions": "This gift card can be redeemed at the locations listed at http://tuscankitchen.instagift.com/gift-card",
                "merchant_instructions": "This gift card originated from the Instagift.com online store for Tuscan Kitchen located at http://tuscankitchen.instagift.com/ Your staff should be trained to accept and validate gifts cards as they arrive. If you have questions, please ask your manager or e-mail support@instagift.com",
                "product_options": [
                    {
                        "id": "mJ1Ie-LkebfAtiCeaCIgFg",
                        "href": "/v2/product_options/mJ1Ie-LkebfAtiCeaCIgFg",
                        "currency": "USD",
                        "face_value_cents": 10000,
                        "price_cents": 10000,
                        "tagline": "$100 Gift Card",
                        "count": null,
                        "limit_per_order": null,
                        "is_recommended": false
                    }
                ],
                "redemption_locations": [
                    {
                        "id": "108esJv3En11Ugc6VZLyCA",
                        "href": "/v2/locations/108esJv3En11Ugc6VZLyCA",
                        "display": "Tuscan Kitchen, 100 Main St., Ste 2, Pleasantville, KS",
                        "name": "Tuscan Kitchen",
                        "address1": "100 Main St.",
                        "address2": "Ste 2",
                        "city": "Pleasantville",
                        "state": "KS",
                        "zip": "67502",
                        "phone": "3166620036",
                        "lat": null,
                        "lng": null
                    }
                ]
            },
            "product_option": {
                "id": "mJ1Ie-LkebfAtiCeaCIgFg",
                "href": "/v2/product_options/mJ1Ie-LkebfAtiCeaCIgFg",
                "currency": "USD",
                "face_value_cents": 10000,
                "price_cents": 10000,
                "tagline": "$100 Gift Card",
                "count": null,
                "limit_per_order": null,
                "is_recommended": false
            },
            "links": {
                "user": "7_JyTOaJuGD5ahUdWGvcnw",
                "parent": null,
                "merchant": "_P07R17NtAZhxN56rneT7A",
                "product": "NnjAQSTtcMcHYZXhRehPVQ"
            },
            "expires_at": null,
            "created_at": "2014-10-09T16:29:44Z",
            "updated_at": "2014-10-09T16:29:44Z"
        }
    ]
}

GET /v2/certificates/:certificate_id USER MERCHANT

Response

Certificate relationships are expanded when fetching an individual certificate (vs list) in order to efficiently provide all the data necessary to display a certificate for redemption.

Parameter Description
href Resource URL for this certificate, will respond to GET requests
product_type GiftCertificate, Deal, or Event
claim_code Can be used to transfer certificate between user accounts
merchant_code Used by the merchant to redeem certificates
status Possible statuses: assigned, cancelled, gifted, pending, redeemed, cancelled, returned
marked_as_printed Certificate owner (user) has specified that he/she has printed the certificate
can_split_value true/false. Certificate face value can be split into smaller denominations
qrcode_image URL to QR Code image
currency Currently only USD
face_value_cents Amount the certificate can be redeemed for
price_cents Amount paid for the certificate
product_redemption_locations_count Number of redemption locations, convenient for display
product_is_print_only true/false. True if mobile redemption is not allowed
product_is_giveaway true/false. True if certificate was created due to a comp or reward
product_seller_name Name of the seller, convenient for display
product_merchant_name Name of merchant, convenient for display. Will be different than seller_name for product type ‘Deal’
product_title Title of the product, convenient for display
seller (deprecated) Name of the seller, convenient for display. Deprecated, replaced by product_seller_name
title (deprecated) Title of the product, convenient for display. Deprected, replaced by product_title
thumb Small image of the product / merchant, convenient for display
expires_at Datetime the certificate can no longer be redeemed for full face value.
daily_deal_store Third party store information if the seller of this certificate was a daily deal store.

Relationships

Name Description
user User details for the certificate owner
parent Present if this certificate was created due to a partial redemption or split
merchant Merchant details for this certificate
product Product details for this certificate

List all Certificates

Sample request(s)

curl https://api.instagift.com/v2/certificates
curl https://api.instagift.com/v2/certificates?status=available&product_type=Event&list_type=available&page=2

Sample response

{
    "links": {
        "certificates.user": "/v2/users/{certificates.user}",
        "certificates.parent": "/v2/certificates/{certificates.parent}",
        "certificates.merchant": "/v2/merchants/{certificates.merchant}",
        "certificates.product": "/v2/merchants/{certificates.product}"
    },
    "meta": {
        "href": "?per_page=10&page=1",
        "page": 1,
        "per_page": 10,
        "page_count": 1,
        "total_count": 13,
        "links": {
            "first": "?per_page=10&page=1",
            "previous": null,
            "next": null,
            "last": "?per_page=10&page=1"
        }
    },
    "certificates": [
        {
            "id": "sD-2VrA6hxAj8FVnoSc_gw",
            "parent_id": null,
            "href": "/v2/certificates/sD-2VrA6hxAj8FVnoSc_gw",
            "product_type": "GiftCertificate",
            "claim_code": "E69W-CDQ2-WTWH6Y",
            "merchant_code": "WTWH6Y",
            "status": "assigned",
            "marked_as_printed": false,
            "can_split_value": true,
            "qrcode_image": "/system/qrcodes/sD-2VrA6hxAj8FVnoSc_gw.png",
            "currency": "USD",
            "face_value_cents": 10000,
            "price_cents": 10000,
            "product_redemption_locations_count": 1,
            "product_is_print_only": false,
            "product_is_giveaway": false,
            "product_seller_name": "Tuscan Kitchen",
            "product_merchant_name": "Tuscan Kitchen",
            "product_title": "$100 Tuscan Kitchen eGift Card",
            "thumb": null,
            "links": {
                "user": "srX0Fin8wFfJ1TEcffTj0w",
                "merchant": "NNA6XfwMj9XUCf58V1_u-Q",
                "product": "tQpEkvBp2E0oH1zRiP6RLQ",
                "product_option": "RjOWgOhoYf-SETVcyMjJEw"
            },
            "expires_at": null,
            "created_at": "2014-10-08T18:15:21Z",
            "updated_at": "2014-10-08T18:15:21Z"
        },
        {
            "...": "..."
        }
    ]
}

GET /v2/certificates USER MERCHANT

Request Parameters

Parameter Required Description
list_type false Possible statuses: ‘all’ and ‘available’. Defaults to all. USER
product_type false Possible product_types: ‘Deal’, ‘Event’, ‘GiftCertificate’. Defaults to all types. USER
page false 1 to n. Defaults to 1.

Response

Relationships are not expanded in list view. See Fetch a Certificate for expanded response.

Split a Certificate

Sample request(s)

curl -X POST https://api.instagift.com/v2/certificates/eSilaL3ev7w3UXvssQ_xFA/certificates \
-H "Content-Type: application/json" \
-d '{"new_face_value_cents":"4000"}' \

Sample response

{
    "links": {
        "certificates.parent": "/v2/certificates/{certificates.parent}",
        "...": "..."
    },
    "certificates": [
        {
            "id": "TZkfX5yZgWGPVyVHi8FVqg",
            "href": "/v2/certificates/TZkfX5yZgWGPVyVHi8FVqg",
            "face_value_cents": 6000,
            "...": "...",
            "links": {
                "parent": null,
                "...": "..."
            }
        },
        {
            "id": "NArlAnTTTnXrL1n_DWJA9w",
            "href": "/v2/certificates/NArlAnTTTnXrL1n_DWJA9w",
            "face_value_cents": 4000,
            "...": "...",
            "links": {
                "parent": "TZkfX5yZgWGPVyVHi8FVqg",
                "...": "..."
            }
        }
    ]
}

POST /v2/certificates/:certificate_id/certificates USER

Request Parameters

Parameter Required Description
face_value_cents false Possible product_types: ‘Deal’, ‘Event’, ‘GiftCertificate’. Defaults to all types. USER

Response

In a successful split, two unexpanded certificates are returned. The child certificate will have a parent relationship pointing to the original certificate.

Redeem a Certificate

Sample request(s)

curl -X POST https://api.instagift.com/v2/certificates/eSilaL3ev7w3UXvssQ_xFA/redemptions \
-H "Content-Type: application/json" \
-d '{"amount_to_redeem_cents":"4000", "redemption_location_id":"AzoXEYPYxG3OUaKJi234WQ"}' \

Sample response

{
    "links": {
        "...": "...",
        "redemptions.location": "/v2/locations/{redemptions.location}"
    },
    "redemptions": [
        {
            "id": "f_OGwyVpgEBgRf-nh-0faA",
            "href": "/v2/redemptions/f_OGwyVpgEBgRf-nh-0faA",
            "amount_cents": 4000,
            "...": "...",
            "links": {
                "location": "AzoXEYPYxG3OUaKJi234WQ",
                "...":"..."
            }
        }
    ]
}

POST /v2/certificates/:certificate_id/redemptions USER MERCHANT

Request Parameters

Parameter Required Description
amount_to_redeem_cents false Amount to redeem. If none is passed, the entire certificate face value is redeemed.
redemption_location_id false Location where the certificate is being redeemed

Response

201 Created See Fetch a Redemption

Relationships

See Fetch a Redemption

Gift a Certificate

Sample request(s)

curl -X POST https://api.instagift.com/v2/certificates/fBkhLlMVLUYpFOjkAvMTbQ/gifts \
    -H "Content-Type: application/json" \
    -d '{"gift":{"sender_name": "Sender Schmidt", "sender_reply_to": "sender@example.com", "recipient_name": "Receiver Rogers", "recipient_email": "receiver@example.com", "message": "Enjoy this gift!"}}' \

Sample response

{
    "links": {
        "...": "..."
    },
    "gifts": [
        {
            "id": "Kk8dw5jSaf2oyzLMet9CLA",
            "href": "/v2/gifts/Kk8dw5jSaf2oyzLMet9CLA",
            "...": "..."
        }
    ]
}

POST /v2/certificates/:certificate_id/gifts USER

Request Parameters

Parameter Required Description
gift true A JSON object containing the gift information. {“gift”:{“sender_name”: “John Doe”, “recipient_email”: “receiver@example.com”}
gift.sender_name true Name of the certificate owner who is sending the gift
gift.sender_reply_to false Reply email address of the certificate owner who is sending the gift
gift.recipient_name false Gift recipient’s name
gift.recipient_email true Email address where to send the gift
gift.message false Personal message to include in the gift email
gift.send_date false Date when the gift should be sent. All future gifts send at or around 3AM ET on date specified. Defaults to immediate send.

Response

201 Created See Fetch a Gift

Relationships

See Fetch a Gift

Claim Codes

Fetch a Certificate by Claim Code

Sample request

curl https://api.instagift.com/v2/claim_codes/E69W-CDQ2-WTWH6Y

Sample response

{
    "links": {
        "certificates.user": "/v2/users/{certificates.user}",
        "certificates.parent": "/v2/certificates/{certificates.parent}",
        "certificates.merchant": "/v2/merchants/{certificates.merchant}",
        "certificates.product": "/v2/merchants/{certificates.product}"
    },
    "certificates": [
        {
            "id": "sD-2VrA6hxAj8FVnoSc_gw",
            "parent_id": null,
            "href": "/v2/certificates/sD-2VrA6hxAj8FVnoSc_gw",
            "product_type": "GiftCertificate",
            "claim_code": "E69W-CDQ2-WTWH6Y",
            "merchant_code": "WTWH6Y",
            "status": "assigned",
            "marked_as_printed": false,
            "can_split_value": true,
            "qrcode_image": "/system/qrcodes/sD-2VrA6hxAj8FVnoSc_gw.png",
            "currency": "USD",
            "face_value_cents": 10000,
            "price_cents": 10000,
            "seller": "Tuscan Kitchen",
            "title": "$100 Tuscan Kitchen eGift Card",
            "thumb": null,
            "links": {
                "user": "srX0Fin8wFfJ1TEcffTj0w",
                "merchant": "NNA6XfwMj9XUCf58V1_u-Q",
                "product": "tQpEkvBp2E0oH1zRiP6RLQ",
                "product_option": "RjOWgOhoYf-SETVcyMjJEw"
            },
            "expires_at": null,
            "created_at": "2014-10-08T18:15:21Z",
            "updated_at": "2014-10-08T18:15:21Z"
        }
    ]
}

GET /v2/claim_code/:claim_code MERCHANT

Response

Certificate relationships are not expanded in claim code view. See Fetch a Certificate for expanded response.

Relationships

See Fetch a Certificate

Redeem a Certificate by Claim Code

Sample request(s)

curl -X POST https://api.instagift.com/v2/claim_codes/E69W-CDQ2-WTWH6Y/redemptions \
-H "Content-Type: application/json" \
-d '{"amount_to_redeem_cents":"4000"}' \

Sample response

{
    "links": {
        "...": "..."
    },
    "redemptions": [
        {
            "id": "f_OGwyVpgEBgRf-nh-0faA",
            "href": "/v2/redemptions/f_OGwyVpgEBgRf-nh-0faA",
            "amount_cents": 4000,
            "...": "..."
        }
    ]
}

Sample errors

{
    "errors": [
        {
            "code": "400",
            "status": "Bad Request",
            "details": "This item has previously been redeemed",
            "title": "Unable to create redemption"
        }
    ]
}
{
    "errors": [
        {
            "code": "401",
            "status": "Unauthorized",
            "title": "Permission denied"
        }
    ]
}
{
    "errors": [
        {
            "code": "404",
            "status": "Not Found",
            "title": "Resource with that ID not found"
        }
    ]
}

POST /v2/claim_codes/:claim_code/redemptions MERCHANT

Request Parameters

Parameter Required Description
amount_to_redeem_cents false Amount to redeem. If none is passed, the entire certificate face value is redeemed.

Response

201 Created See Fetch a Redemption

Errors

Error response JSON includes “code”, “status”, “title”, and “details”. The HTTP status code should match the response “code”.

Code Status Title Details
400 Bad Request Unable to create redemption That item is not available for redemption
400 Bad Request Unable to create redemption This item has previously been redeemed
400 Bad Request Unable to create redemption This item has been refunded to the customer
400 Bad Request Unable to create redemption You must select a redemption location
401 Unauthorized Permission denied
404 Not Found Resource with that ID not found

Relationships

See Fetch a Redemption

Claim a Certificate by Claim Code

Sample request(s)

curl -X PUT https://api.instagift.com/v2/certificates/E69W-CDQ2-WTWH6Y

Sample response

{
    "links": {
        "certificates.user": "/v2/users/{certificates.user}",
        "...": "..."
    },
    "certificates": [
        {
            "id": "hD65TJvxnv8oIuyOmD056w",
            "href": "/v2/certificates/hD65TJvxnv8oIuyOmD056w",
            "...": "...",
            "links": {
                "user": "7_JyTOaJuGD5ahUdWGvcnw",
                "...":"..."
            }
        }
    ]
}

PUT /v2/certificates/:claim_code USER

Request

If a valid certificate with the claim code is found, the certificate ownership will update to the authenticated user making the request.

Response

See Fetch a Certificate

Comps

Coming Soon

Customers

Coming Soon

Gifts

Fetch a Gift

Sample request

curl https://api.instagift.com/v2/gifts/Kk8dw5jSaf2oyzLMet9CLA/gifts

Sample response

{
    "links": {
        "gifts.certificate": "/v2/certificates/{gifts.certificate}",
        "gifts.sender": "/v2/users/{gifts.sender}",
        "gifts.recipient": "/v2/users/{gifts.recipient}"
    },
    "gifts": [
        {
            "id": "Kk8dw5jSaf2oyzLMet9CLA",
            "href": "/v2/gifts/Kk8dw5jSaf2oyzLMet9CLA",
            "sender_name": "Sender Schmidt",
            "sender_reply_to": "sender@example.com",
            "recipient_name": "Receiver Rogers",
            "recipient_email": "recipient@example.com",
            "message": "I hope you enjoy a night out on me!",
            "send_date": null,
            "claimed_at": null,
            "last_sent_at": "2014-10-09T18:42:31Z",
            "attempts": 1,
            "failure_count": 0,
            "links": {
                "certificate": "uNgmH1EPY6VKj3khdRFo0w",
                "sender": "ypRuj-KYopAl_yF2PqXlfg",
                "recipient": null
            },
            "created_at": "2014-10-09T18:42:30Z",
            "updated_at": "2014-10-09T18:42:31Z"
        }
    ]
}

GET /v2/gifts/:gift_id USER

Response

Parameter Description
href Resource URL for this gift, will respond to GET requests
sender_name Name of the certificate owner who is sending the gift
sender_reply_to Reply email address of the certificate owner who is sending the gift
recipient_name Gift recipient’s name
recipient_email Email address where to send the gift
message Personal message to include in the gift email
send_date Date when the gift should be sent. All future gifts send at or around 3AM ET on date specified. Defaults to immediate send.
claimed_at Datetime when the recipient claims the gift. null until claimed
last_sent_at Datetime indicating the last time Instagift attempted to deliver the gift email
attempts Number of times the gift has been sent
failure_count Number of times the gift failed to send

Relationships

Name Description
certificate Certificate being gifted
sender User who sent the gift
recipient User who received the gift. Null until claimed.

List all Gifts

Sample request

curl https://api.instagift.com/v2/gifts

Sample response

{
    "links": {
        "...": "..."
    },
    "gifts": [
        {
            "id": "Kk8dw5jSaf2oyzLMet9CLA",
            "href": "/v2/gifts/Kk8dw5jSaf2oyzLMet9CLA",
            "...": "..."
        },
        {
            "...": "..."
        }
    ]
}

GET /v2/gifts USER

Response

Array of gifts

Locations

Fetch a Location

Sample request

curl https://api.instagift.com/v2/locations/AzoXEYPYxG3OUaKJi234WQ

Sample response

{
    "links": {
        "locations.merchant": "/v2/merchants/{locations.merchant}"
    },
    "locations": [
        {
            "id": "_xVSvoERC3KV6vdcKWgjIw",
            "href": "/v2/locations/_xVSvoERC3KV6vdcKWgjIw",
            "display": "Tuscan Kitchen, Tuscan Kitchen 2, 100 Main St., Ste 2, Pleasantville, KS",
            "name": "Tuscan Kitchen 2",
            "address1": "100 Main St.",
            "address2": "Ste 2",
            "city": "Pleasantville",
            "state": "KS",
            "zip": "67502",
            "phone": "3166620036",
            "lat": 38.081600000000,
            "lng": -97.931500000000,
            "links": {
                "merchant": "BZegPI8u-9Qj8UCVfxosbw"
            },
            "created_at": "2014-10-10T13:17:13Z",
            "updated_at": "2014-10-10T13:17:13Z"
        }
    ]
}

GET /v2/locations/:location_id PUBLIC

Response

Parameter Description
href Resource URL for this location, will respond to GET requests
display String combining the name, address, city and state for convenience
name Null allowed. Useful to explain a merchant’s multiple locations
address1 Required
address2 Null allowed
city
state Standard USPS or ANSI two letter code
zip Standard 5 or 9 digit US zip code
phone 10 digits, unformatted.
lat Null allowed
lng Null allowed

Relationships

Name Description
merchant Merchant details for this certificate

List all Locations for a Merchant

Sample request

curl https://api.instagift.com/v2/merchants/AzoXEYPYxG3OUaKJi234WQ/locations

Sample response

{
    "links": {
        "locations.merchant": "/v2/merchants/{locations.merchant}"
    },
    "locations": [
        {
            "id": "aU1Tefis_JCcbHhs0Rl30g",
            "href": "/v2/locations/aU1Tefis_JCcbHhs0Rl30g",
            "...": "...",
            "links": {
                "merchant": "yk2aWtv97ZbEjVH0E_511g"
            }
        },
        {
            "...": "..."
        }
    ]
}

GET /v2/merchant/:merchant_id/locations PUBLIC

Response

Array of locations

List Redemption Locations for a Product

Sample request

curl https://api.instagift.com/v2/products/LJJ306Z-MDQs6ppbP_55TQ/locations

Sample response

{
    "links": {
        "locations.product": "/v2/products/{locations.product}"
    },
    "locations": [
        {
            "id": "LJJ306Z-MDQs6ppbP_55TQ",
            "href": "/v2/locations/LJJ306Z-MDQs6ppbP_55TQ",
            "...": "...",
            "links": {
                "product": "VYDlYME879dbz7Mj0JoLsA"
            }
        },
        {
            "...": "..."
        }
    ]
}

GET /v2/product/:product_id/locations PUBLIC

Response

Array of locations

Merchants

Fetch a Merchant

Sample request

curl https://api.instagift.com/v2/merchants/AzoXEYPYxG3OUaKJi234WQ

Sample response

{
    "links": {
        "merchants.locations": "/v2/merchants/{merchants.id}/locations"
    },
    "merchants": [
        {
            "id": "PiIxGa518njpRGYCSXrarg",
            "href": "/v2/merchants/PiIxGa518njpRGYCSXrarg",
            "url": "http://tuscankitchen.instagift.com/",
            "name": "Tuscan Kitchen",
            "time_zone": "Eastern Time (US & Canada)",
            "logo": "/logos/original/missing.png",
            "created_at": "2014-10-10T14:05:32Z",
            "updated_at": "2014-10-10T14:05:32Z"
        }
    ]
}

GET /v2/merchants/:merchant_id PUBLIC

Response

Parameter Description
href Resource URL for this merchant, will respond to GET requests

Relationships

Name Description
locations Array of a merchant’s locations

Generate an API Key

Coming soon

Passwords

Reset Password

Sample request

curl -X POST https://api.instagift.com/v2/passwords \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com"}' \

Sample response

{
  "data": {
    "title": "Password reset sent",
    "email": "person@example.com"
  }
}

POST /v2/passwords PUBLIC

Request Parameters

Parameter Required Description
email true A valid email address for an Instagift user account

Response

201 Created

Products

Fetch a Product

Sample request

curl https://api.instagift.com/v2/products/AzoXEYPYxG3OUaKJi234WQ

Sample response

{
    "links": {
        "products.merchant": "/v2/merchants/{products.merchant}",
        "products.redemption_locations": "/v2/products/{products.id}/locations",
        "products.product_options": "/v2/products/{products.id}/product_options"
    },
    "products": [
        {
            "id": "Kpu_xWu_0jy746VfKMO4ag",
            "href": "http://tuscankitchen.instagift.com/gift-card",
            "type": "GiftCertificate",
            "discount_sale_name": null,
            "is_giveaway": false,
            "is_print_only": false,
            "can_split_value": true,
            "gift_card_image": "//s3.amazonaws.com/assets.dealcoop.com/gift_cards/63001/original.jpg?1386187921",
            "photos": [],
            "headline": null,
            "tagline": "Tuscan Kitchen eGift Card",
            "terms": [
                "Good on any food or drink",
                "Can be used on tax and gratuity",
                "Does not expire",
                "Merchant are not required to give change for the unused balance"
            ],
            "expiration_instructions": "Unless otherwise noted, this gift card NEVER EXPIRES",
            "redemption_instructions": "This gift card can be redeemed at the locations listed at http://tuscankitchen.instagift.com/gift-card",
            "merchant_instructions": "This gift card originated from the Instagift.com online store for Tuscan Kitchen located at http://tuscankitchen.instagift.com/ Your staff should be trained to accept and validate gifts cards as they arrive. If you have questions, please ask your manager or e-mail support@instagift.com",
            "links": {
                "merchant": "KnWauxXPaBrwd4xnmUoqCA"
            },
            "created_at": "2014-10-10T14:55:42Z",
            "updated_at": "2014-10-10T14:55:42Z"
        }
    ]
}

GET /v2/products/:product_id PUBLIC

Response

Parameter Description
href Resource URL for this product, will respond to GET requests
type GiftCertificate, Event, or Deal
discount_sale_name Some type=Deal belong to this special kind of sale
is_giveaway Was this issued as a comp, reward, or giveaway?
is_print_only Does the merchant allow certificates for this product to be redeemed via mobile? If false, mobile redemption should be disabled.
can_split_value Certificate face value can be split
gift_card_image Image of the gift card
photos[] Events and Deals can include a photo gallery
headline Short title, null for type=GiftCertificate
tagline Longer title
terms[] The fine print for a product
expiration_instructions Details about the expiration of this product, and its certificates
redemption_instructions Intended for consumers, how to redeem certificates
merchant_instructions Intended for merchant staff, explanation of what and where the certificates came from

Relationships

Name Description
merchant Merchant details for this certificate
redemption_locations Location details for each product redemption location
product_options Pricing/purchase options for this product

Product Options

Fetch a Product Option

Sample request

curl https://api.instagift.com/v2/product_options/AzoXEYPYxG3OUaKJi234WQ

Sample response

{
    "links": {
        "product_options.product": "/v2/products/{product_options.product}"
    },
    "product_options": [
        {
            "id": "uWlrlf8fBTseVC5gF96H5w",
            "href": "/v2/product_options/uWlrlf8fBTseVC5gF96H5w",
            "currency": "USD",
            "face_value_cents": 10000,
            "price_cents": 10000,
            "tagline": "$100 Gift Card",
            "count": null,
            "limit_per_order": null,
            "is_recommended": true,
            "links": {
                "product": "udTPAbSavpDKUjqcUPyPMQ"
            },
            "created_at": "2014-10-10T15:08:29Z",
            "updated_at": "2014-10-10T15:08:29Z"
        }
    ]
}

GET /v2/product_options/:product_option_id PUBLIC

Response

Parameter Description
href Resource URL for this product option, will respond to GET requests
currency ISO 4217 currency codes. Most likely “USD”
face_value_cents Amount certificates from this product_option can be redeemed for
price_cents Price consumers will pay for certificates from this product_option
tagline Helpful to describe the differences between product options for a product
count Inventory. Null means unlimited
limit_per_order Number consumers are allowed to purchase per order
is_recommended The option that the merchant or Instagift recommend that a consumer purchase

Relationships

Name Description
product Product this pricing option belongs to

List Product Options for a Product

Sample request

curl https://api.instagift.com/v2/products/AzoXEYPYxG3OUaKJi234WQ/product_options

Sample response

{
    "links": {
        "product_options.product": "/v2/products/{product_options.product}"
    },
    "product_options": [
        {
            "id": "aT6dCx3pRkoMgCnoAfrlpA",
            "href": "/v2/product_options/aT6dCx3pRkoMgCnoAfrlpA",
            "...": "...",
            "links": {
                "product": "FBHf_LcvfYsMqEFxf1Dmdg"
            }
        },
        {
            "...": "..."
        }
    ]
}

GET /v2/products/:product_id/product_options PUBLIC

Response

Array of product options

Redemptions

Fetch a Redemption

Sample request(s)

curl https://api.instagift.com/v2/redemptions/f_OGwyVpgEBgRf-nh-0faA

Sample response

{
    "links": {
        "redemptions.certificate": "/v2/certificates/{redemptions.certificate}",
        "redemptions.user": "/v2/users/{redemptions.user}",
        "redemptions.merchant": "/v2/merchants/{redemptions.merchant}",
        "redemptions.location": "/v2/locations/{redemptions.location}"
    },
    "redemptions": [
        {
            "id": "f_OGwyVpgEBgRf-nh-0faA",
            "href": "/v2/redemptions/f_OGwyVpgEBgRf-nh-0faA",
            "amount_cents": 10000,
            "amount_paid_cents": 10000,
            "source": "api-v2-user",
            "links": {
                "certificate": "-3qdxkN_aoAwoX4byOLmrQ",
                "user": "IRxn4SmMQlDjM7bVlIfl5w",
                "merchant": "WnDQkpaFftq5w1G8PX2Rpg",
                "location": "DBVMHAdRRRjdfUFGJZzRPw"
            },
            "created_at": "2014-10-09T18:08:43Z",
            "updated_at": "2014-10-09T18:08:43Z"
        }
    ]
}

GET /v2/redemptions/:redemption_id USER MERCHANT

Response

Parameter Description
href Resource URL for this redemption, will respond to GET requests
amount_cents Amount redeemed in cents
amount_paid_cents Amount paid for the redeemed certificate (if it was purchased at discount)
source Used by the merchant to redeem certificates

Relationships

Name Description
certificate Certificate that was redeemed
user User details for the redeemer
merchant Merchant where the certificate was redeemed
location Location where the certificate was redeemed

List all Redemptions

Sample request

curl https://api.instagift.com/v2/redemptions

Sample response

{
    "links": {
        "...": "..."
    },
    "redemptions": [
        {
            "id": "f_OGwyVpgEBgRf-nh-0faA",
            "href": "/v2/gifts/f_OGwyVpgEBgRf-nh-0faA",
            "...": "..."
        },
        {
            "...": "..."
        }
    ]
}

GET /v2/redemptions USER MERCHANT

Response

Array of redemptions

Support Tickets

Comin soon, sample requests and responses included for testing. Subject to change.

Create a Support Ticket

Sample request

curl -X POST https://api.instagift.com/v2/support_tickets \
    -H "Content-Type: application/json" \
    -d '{"name":"John Doe,"email":"person@example.com","message":"I can't access my account"}'

POST /v2/support_tickets PUBLIC

Request

Parameter Required Description
name true Requester’s name
email true Requester’s email address
message true Description of the support issue or question

Response

201 Created

Users

Fetch a User

Sample request

curl https://api.instagift.com/v2/users/sYdLUTYH8eVD-p6zIVn30g

Sample response

{
    "links": {
        "user.certificates": "/v2/user/{users.id}/certificates",
        "user.sent_gifts": "/v2/user/{users.id}/gifts",
        "user.redemptions": "/v2/user/{users.id}/redemptions"
    },
    "users": [
        {
            "id": "sYdLUTYH8eVD-p6zIVn30g",
            "href": "/v2/users/728",
            "name": "John Doe",
            "email": "person@example.com",
            "authentication_token": "nh6W4t-ffsbT-xRp6k_h",
            "last_login_at": "2014-10-10T15:39:36Z",
            "created_at": "2014-10-10T15:39:36Z",
            "updated_at": "2014-10-10T15:39:36Z"
        }
    ]
}

GET /v2/users/:user_id USER MERCHANT

Response

Parameter Description
href Resource URL for this product option, will respond to GET requests
name User’s registered name
email User’s email, used for authentication, order confirmations, notifications, etc. Only visible to an authenticated user.
authentication_token Used for API authentication. Only visible to an authenticated user.
last_login_at Datetime the user last logged in to Instagift

Relationships

Name Description
certificates A list of a user’s certificates
gifts Both sent and received gifts
redemptions A list of a user’s redemptions

Create a User

Sample request

curl -X POST https://api.instagift.com/v2/users \
    -H "Content-Type: application/json" \
    -d '{"user":{"email":"person@example.com","password":"testing1234","password_confirmation":"testing12345","first_name":"John","last_name":"Doe"}}'

Sample response

{
    "links": {
        "...": "..."
    },
    "users": [
        {
            "id": "sYdLUTYH8eVD-p6zIVn30g",
            "href": "/v2/users/728",
            "authentication_token": "nh6W4t-ffsbT-xRp6k_h",
            "...": "..."
        }
    ]
}

GET /v2/users/:user_id PUBLIC

Request

Parameter Required Description
user true A JSON object of a user’s registration info. { “user” : { “email” : “person@example.com”, “password” : “testing1234”, “password_confirmation” : “testing12345”, “first_name” : “John”, “last_name” : “Doe” } }
user.email true Must be valid and not already registered
user.password true Must be at least 5 characters
user.password_confirmation true Must match password
user.first_name false
user.last_name false

Response

201 Created See Fetch a User

Tokens

Request User Token

Sample request

curl -X POST https://api.instagift.com/v2/tokens \
  -H "Content-Type: application/json" \
  -d '{"user":{"email":"person@example.com","password":"testing1234"}}'

Sample response

{
  "links": {
    "user.certificates": "/v2/user/{users.id}/certificates",
    "user.redemptions": "/v2/user/{users.id}/redemptions",
    "user.gifts": "/v2/user/{users.id}/gifts"
  },
  "users": [
    {
      "id": "GddXpGdvs3V89PkUwCSoIg",
      "href": "/v2/users/GddXpGdvs3V89PkUwCSoIg",
      "email": "person@example.com",
      "name": "Tester Joe",
      "authentication_token": "quhZKsGMSJc5eUAYm-FA",
      "last_login_at": "2014-07-09T01:41:41Z"
    }
  ]
}

POST /v2/tokens PUBLIC

Request Parameters

Parameter Required Description
user true A JSON object of a user’s credentials. { user: { email: “person@example.com”, password: “testing1234” } }
user.email true Email address to authenticate
user.password true User’s password

Response

Parameter Description
href Resource URL for this user, will respond to GET requests
email User’s email address, used for API authentication
authentication_token Token used for API authentication
last_login_at Datetime of last login

Relationships

Name Description
certificates A collection of certificates for this user
redemptions A collection of redemption for this user
gifts A collection of gifts for this user

Reset User Token

Sample request

curl -i -X DELETE https://api.instagift.com/v2/tokens \
  -H "Content-Type: application/json" \
  -H "X-User-Email: person@example.com" \
  -H "X-User-Token: quhZKsGMSJc5eUAYm-FA" \

DELETE /v2/tokens USER

Response

204 No Content

Ecommerce Integration

Overview

This section is intended to serve as a guide for Instagift merchant customers who wish to integrate Instagift into the ecommerce portion of their website using the Instagift API. It is for webmasters that have built, or have a high degree of control over, their ecommerce environment. If you are running ecommerce through a service like Shopify, Squarespace, or Miva Merchant, this guide is probably not for you.

Merchant authentication and API Keys

You can create an API key in your Instagift Merchant Dashboard under Settings → API Keys. A GROW plan is required. See Authentication for more information about making authenticated merchant API requests.

Note about “certificates”

This guide refers to all Instagift issued virtual gift cards, event tickets, gift certificates, coupons and other various types of printed vouchers as “certificates”.

Integration Steps

When integrating Instagift gift and reward card redemption into your checkout flow, these are the basic steps required:

  1. During checkout, your customers will need the ability to apply an “Instagift Claim Code” towards the balance of their order. This input box should be appropriately labeled “Instagift Claim Code”. Claim codes are displayed on each Instagift certificate. Claim codes include both letters and numbers and are typically 13 to 15 characters long. Example claim codes: “MNK-QPF27E-EHJ3”, “U4KR-9CLT-3KNPU4”
  2. Using the Instagift API, your ecommerce system should fetch the certificate by claim code to check validity and balance. Merchant authentication required.
  3. If the claim code is valid, your ecommerce system should apply all or part (if allowed) of the certificate’s face value to the customer’s current order.
  4. After successful checkout, your system should redeem the certificate by claim code, specifying the amount (amount_to_redeem_cents) to deduct from the Instagift certificate balance. Merchant authentication required.

Partial Redemption

API parameters and values are bold.

can_split_value

If a certificate can_split_value is true, you can submit a amount_to_redeem_cents for less than the certificate’s face_value_cents. A successful partial redemption will result in:

  1. The face_value_cents of the certificate will be lowered to the redemption amount
  2. The certificate status will be updated to redeemed
  3. A new certificate will be placed in the users account for the balance. They can use this new certificate (with a new claim code) at a later date.

If a certificate can_split_value is false, the entire certificate face value will be redeemed. This should be made apparent to the user in order to avoid confusion.

Dollars vs Cents

Currently, the Instagift API does not allow for redemption amounts that are not whole numbers. If you submit a redemption amount_to_redeem_cents of 2381 ($23.81), you’ll receive a redemption response for 2300 ($23.00), which is the amount_to_redeem_cents rounded down to the nearest integer. If a fetch reveals that a user has a certificate for $100, and they owe $52.50 for your order, you can either:

We may revisit this in the future.

Errors

The Instagift API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is somehow invalid or missing required information
401 Unauthorized – Your authorization credentials are missing or incorrect for the resource you’re trying to access
404 Not Found – The resource id you provided cannot be found
406 Not Acceptable – Your request isn’t JSON
429 Too Many Requests – You’ve reached your rate limit
500 Internal Server Error – We had a problem with our server. Try again later.
cURL