Submit an Order

This operation allows a user to submit an order for a donation without submitting payment details. This allows GlobalGiving the ability to immediately update a project's funded status 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/orders

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 order will not be registered in the GlobalGiving system

Query String Example:

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

Data Parameters:

refcode - your external identifier for this request which is returned in the response, required (maximum 100 characters)

transactionId - your unique transaction identifier for this transaction stored in our records for future reference and possible reporting, optional (maximum 100 characters)

email - required (maximum 50 characters)

amount - a numeric value greater than one, required

currencyCode - optional; Defaults to USD

addon; - optional

amount - a numeric value greater than zero, required if addon element is provided

project;

id - the numeric identifier for a project, required

signupForGGNewsletter - optional; defaults to false

signupForCharityNewsletter - optional; defaults to false

noteToOrganization - optional (maximum 255 characters)You must have a special agreement to have this parameter recognized.

partnerCode - optional (maximum 40 characters)You must have a special agreement to have this parameter recognized.

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'?>
                  <order>
                     <refcode>123456789</refcode>
                     <transactionId>abc123</transactionId>
                     <email>john.doe@hotmail.com</email>
                     <amount>25</amount>
                     <currencyCode>USD</currencyCode>
                     <project>
                        <id>1883</id>
                     </project>
                     <signupForGGNewsletter>true</signupForGGNewsletter>
                     <signupForCharityNewsletter>true</signupForCharityNewsletter>
                  </order>" -X POST "https://api.globalgiving.org/api/secure/givingservice/orders?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"?>
                  <invoice>
                     <amount>25.00</amount>
                     <currencyCode>USD</currencyCode>
                     <datetime>2008-08-21T18:26:22.717-07:00</datetime>
                     <email>john.doe@hotmail.com</email>
                     <project>
                        <funding>5897.47</funding>
                        <goal>62500</goal>
                        <id>1883</id>
                        <numberOfDonations>75</numberOfDonations>
                        <progressReportLink>http://www.globalgiving.org/pr/1900/proj1883a.html#progressReports</progressReportLink>
                        <projectLink>http://www.globalgiving.org/pr/1900/proj1883a.html</progressReportLink>
                        <remaining>56602.53</remaining>
                     </project>
                     <refcode>123456789</refcode>                     
                     <signupForCharityNewsletter>true</signupForCharityNewsletter>
                     <signupForGGNewsletter>true</signupForGGNewsletter>
                     <transactionId>abc123</transactionId>
                     <invoiceNumber>I49578-GC174282-CBcb01</invoiceNumber>
                  </invoice>

NOTE: If successful, response contains <invoiceNumber>, and <datetime> elements.

Submit an Order Request Structure

order
refcode string
transactionId string
email string
amount decimal
currencyCode string
addon
amount decimal
project
id int
signupForGGNewsletter boolean
signupForCharityNewsletter boolean
noteToOrganization String
partnerCode String

Element Definitions for Submit an Order Request

Element Mandatory Description
refcode required The external identifier (maximum 100 characters) of the person who submitted the request which is returned in the response.
transactionId optional Your unique transaction identifier (maximum 100 characters) for this transaction stored in our records for future reference and possible reporting.
email required Email of user that order is placed for.
amount required Order amount.
currencyCode optional; defaults to USD Contact GlobalGiving about using any currency other than USD
addon -> amount required if addon element was provided Add on donation amount funding GlobalGiving's operational expenses.
project -> id required Unique identifier for a GlobalGiving project.
signupForGGNewsletter optional True if user should receive GlobalGiving newsletter. Default is false.
signupForCharityNewsletter optional True if user should receive Charity newsletter. Default is false.
noteToOrganization optional * This "note" will be forwarded to the Organization when the donation is disbursed (maximum 255 characters)
partnerCode optional * A partnerCode associated with this API Key for users with this functionality enabled.

* - Field is only recognized if api key has special permission to post notes to the organization. Please contact us with questions. Submitting this field is optional, and values will be ignored if your key does not have the permission to use.

Order Response Structure

invoice
amount decimal
invoicedAmount decimal
curencyCode string
addon
amount decimal
datetime dateTime
email string
project
funding decimal
goal decimal
id int
numberOfDonations int
progressReportLink string
projectLink string
remaining decimal
refcode string
signupForCharityNewsletter boolean
signupForGGNewsletter boolean
transactionId string
invoiceNumber string
noteToOrganization String
partnerCode String

Element Definitions for Order Response

Element Mandatory Description
amount required Amount owing for invoice.
invoicedAmount required Total order amount that was invoiced. The sum of amount and addon amount.
currencyCode required The currency that the invoice was recorded in. Will always be USD, unless you make special arrangements to acquire a GlobalGiving UK api key
addon -> amount required if addon element was provided Add on donation amount funding GlobalGiving's operational expenses.
datetime required Date time of when donation order was placed (format YYYY-MM-DDThh:mm:ss[.s[s*]][TZD]).
email required Email of user that order is placed for.
funding required Total funding project has received to date.
goal required Project goal.
project -> id required Unique identifier for a GlobalGiving project.
numberOfDonations required Total number of donations received to date.
progressReportLink optional URI of progress report for project.
projectLink optional URI of the project.
remaining required Total amount remaining for project to meet its goal.
refcode required The external identifier submitted with the request.
signupForCharityNewsletter required True if user should receive Charity newsletter.
signupForGGNewsletter required True if user should receive GlobalGiving newsletter.
transactionId optional Your external identifier submitted with the request.
invoiceNumber required GlobalGiving unique identifier of invoice order.
noteToOrganization optional * The "note" that will be sent with the funds when disbursed to the organization
partnerCode optional * A partnerCode assoiciated with API KEY with this functionality enabled.

* - This field will only be returned if it was submitted and accepted. See above fields for submitting orders for more.