This API action allows you to purchase a new gift code.
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 requests 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 https://api.donorschoose.org/ as with all non-transactional API traffic)
- all transactions must include a token to prevent duplicate submissions
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. All parameters except APIKey should be sent in the POST body:
| APIKey (required) | Your unique API Key |
| apipassword (required) | Indicate in your API key request that you need to do transactions. |
| action (required) | Must be 'giftcode' for this type of transaction. |
| token (required) | The token you acquired with a previous "token" action |
| callback (optional) | If you wish to wrap your response in a callback function, include the name here. |
Steps to generate a gift code
Generating a gift code through our API requires two steps:
1) Sending a request to obtain a token. This code will be unique and can only be used once.
2) Sending a request to generate the gift code. This request will include the token along with other required parameters.
Obtaining a Transaction Token
You must specify the following parameters:
| action (required) | Must be set to "token" for this step. |
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.) |
The 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 account10 ? "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?APIKey=[YOUR_API_KEY] HTTP/1.1
POST body:
apipassword=sampleapipassword&action=giftcode&token=ABCD-12345-XYXYZ-12345&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?}
Communication
You should communicate the gift code string and denomination to the end-user, as we have no way to do so.
When a live API transaction succeeds, you'll get an email from us detailing the amount of the gift code and your remaining account balance.
Gift Code Functional Limitations
These capabilities of the DonorsChoose 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.