Gift codes

Documentation‎ > ‎Transactions‎ > ‎

This API action allows you to purchase a new gift code.

Contents

1 Protecting Transactions (reminder)
2 Secure API Request URL (reminder)
3 Shared Parameters (reminder)
4 Generate Gift Code Parameters
5 Generate Gift Code Response
6 Generate Gift Code Request Example
7 Generate Gift Code Response Example
8 Gift Code Functional Limitations

Protecting Transactions (reminder)

To ensure the integrity and security of all transactions, we require that...

all transactions must be authenticated with an apipassword which we will issue to you in addition to the regular APIKey.
all parameters must be sent as a POST (rather than a GET) to prevent any servers from logging the apipassword.
all requests be made via HTTPS to our secure API host, see below... (instead of http://api.donorschoose.org/ as with all non-transactional API traffic)

Secure API Request URL (reminder)

All requests should be POSTed to the following URL:

https://apisecure.donorschoose.org/common/json_api.html

Shared Parameters (reminder)

These parameters are shared by all transactional API requests:

APIKey (required)	Request a unique API key.
apipassword (required)	Indicate in your API key request that you need to do transactions.
callback (optional)	If you wish to wrap your response in a callback function, include the name here.
action (required)	Should be 'giftcode' for this type of transaction.

Generate Gift Code Parameters

You specify the value of the gift code and, optionally, the number of months before the gift code expires.

If the transaction succeeds, we'll debit the value of the gift code from the account associated with your APIKey.

amount (required)	Value of gift code to generate. (We recommend whole numbers (no cents) to keep things clean and reduce confusion, since project price tags and donation amounts on our front-end are always whole numbers.)
expirationMonths (optional)	Number of months before gift code expires, maximum of 6 months. (If not specified, defaults to 6 months.)

Generate Gift Code Response

The response includes the actual alphanumeric gift code and the expiration date of the gift code.

statusCode	Numeric status code, one of: 0 - "success" 1 - "insufficient balance": not enough money left in account 10 - "internal error: please retry": an internal database error occurred, retrying the same request should work
statusDescription	String description of error, see above for the strings (do not rely on these strings staying the same, if you want to test for a specific error, use the numeric codes which will not change)
giftCode	The 10-digit gift code
giftCodeExpiration	The gift code's expiration date in YYYY-MM-DD format

Generate Gift Code Request Example

POST /common/json_api.html HTTP/1.1
...

APIKey=SAMPLEAPIKEY&apipassword=sampleapipassword&action=giftcode&amount=125.00&expirationMonths=3

Generate Gift Code Response Example

Here's an example response:

{"statusCode":"0",
"statusDescription":"success",
"giftCode":""ZWR6NOZJ",
"giftCodeExpiration":"2015-02-01"}

Gift Code Functional Limitations

These capabilities of the DonorsChoose.org front-end are not currently available via the API:

You can only purchase one gift card at a time.

You cannot put multiple gift cards in a "cart."
You cannot purchase a batch of gift cards, eg. 15 x $30.

Gift cards can only be supplied in the form of the 10-digit redemption code.

We cannot send a gift card to the recipient via email or postal mail.
We cannot provide you with a printable (PDF) gift card.

Developer Guide