Order a Gift Certificate

This operation allows a user to submit an order for a gift certificate without submitting payment details. This allows GlobalGiving the ability to immediately generate gift certificates with the understanding that reconciliation of the order will take place at a later date. This is a secure request as indicated by the '/secure/' element in the URL path, therefore, an access token (authentication) is required.

NOTE: You must enter into a special agreement with GlobalGiving to use this API feature. Please contact us for more information if you wish to have this feature enabled.

HTTP Method:

POST

Content Type:

xml, json

Accept Type:

xml, json

Path:

https://api.globalgiving.org/api/secure/givingservice/giftcertificates

Query String Parameters:

&api_key described in the API Key section, required

&api_token described in the Access Token section, required

&is_test when set to true the gift certificate order will not be registered in the GlobalGiving system

Query String Example:

/api/secure/givingservice/giftcertificates?api_key=YOUR_API_KEY&api_token=SOME_API_TOKEN

Data Parameters:

refcode - The external batch identifier (maximum 20 characters). This is used for invoicing and should be the same for all orders unless otherwise discussed with the GlobalGiving team.

thirdPartyIdentifier - optional; External identifier to uniquely identify a single gift card. GlobalGiving does not check for/gurantee unique values.

amount - a numeric value greater than one, required

currencyCode - optional; Defaults to USD.

expirationDate - optional; format is YYYY-MM-DD. Defaults to one year after the order is placed. Date cannot be the same day of the order or in the past and cannot be more than two years from the order date.

HTTP POST Request using cURL:

curl -H "Accept: application/xml" -H "Content-Type: application/xml" -d "<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<giftCertificate>
  <refcode>123456789</refcode>
  <amount>25</amount>
  <thirdPartyIdentifier>{D21A1915-E024-4B9C-8345-62BECAE048EF}</thirdPartyIdentifier>
  <currencyCode>USD</currencyCode>
  <expirationDate>2019-12-31</expirationDate>
</giftCertificate>" -X POST "https://api.globalgiving.org/api/secure/givingservice/giftcertificates?api_key=YOUR_API_KEY&api_token=SOME_API_TOKEN"

NOTE: Above request has carriage returns for readability.

XML Response:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<giftCertificate_detail>
  <giftCertificateNumber>GL9476HDT92N</giftCertificateNumber>
  <remainingAmount>25.00</remainingAmount>
  <thirdPartyIdentifier>{D21A1915-E024-4B9C-8345-62BECAE048EF}</thirdPartyIdentifier>
  <currencyCode>USD</currencyCode>
  <redeemUrl>https://www.globalgiving.org/gifts/redeem.html?code=GL9476HDT92N</redeemUrl>
  <expirationDate>2019-12-31T23:59:59-04:00</datetime>
</giftCertificate_detail>

NOTE: If successful, response contains <giftCertificateNumber>, and <redeemUrl> elements.

Order a Gift Certificate Request Structure

giftCertificate

refcode	string
thirdPartyIdentifier	string
amount	decimal
currencyCode	string
expirationDate	string

Element Definitions for Order a Gift Certificate

Element	Mandatory	Description
refcode	required	The external identifier (maximum 20 characters) of the person who submitted the request.
thirdPartyIdentifier	optional	The external identifier (maximum 64 characters) of the person who submitted the request.
amount	required	Gift Certificate amount.
currencyCode	optional; defaults to USD	Contact GlobalGiving about using any currency other than USD
expirationDate	optional; defaults to one year from the date the order is placed	The expiration date of the gift certificate. Must not be in the past or the same day of the order is placed and must be within two years.

Order Gift Certificate Response Structure

giftCertificate_detail

giftCertificateNumber	string
remainingAmount	decimal
curencyCode	string
redeemUrl	string
expirationDate	dateTime

Element Definitions for Order Gift Certificate Response

Element	Mandatory	Description
giftCertificateNumber	required	The generated giftcertid.
remainingAmount	required	Amount of funds remaining on the gift certificate. This will be the same as the amount requested.
currencyCode	required	The currency that the gift certificate was recorded in.
exipirationDate	required	The date of expiration - the gift certificate is good through the expiration date in Eastern US time-zone.
redeemUrl	required	URL to claim the gift certificate.