API v1 Reference

Store Purchases

The store purchase API methods must be submitted in a specific order. The following guide explains the basic workflow for submitting orders using the store API.

1. Create a Shopping Cart

The first necessary step is to create a new shopping cart. This acts as a container that ties the order together. Items are added to the cart, and then the cart is purchased by an account, who is linked to the cart. Once all the necessary information has been added to the cart, you can Checkout to complete the purchase.

2. Add Items to the Shopping Cart

In order to complete a purchase, you must include at least one item in the shopping cart. This can be a donation, membership, or store product. Possible membership terms can be retrieved via listMembershipTerms. Store products and their associated options can be retrieved using listProducts and listProductOptions.

You may use this request multiple times for a single shopping cart.

3. Add a Customer to the Shopping Cart

A purchase must be associated with a single user account. This requires an account ID. You can either create a new one using createIndividualAccount or createOrganizationAccount, or you can retrieve an existing account using any of the listAccounts requests. You can also ask a user to log in using authenticateUser, and use the account Id provided in the response.

4. Shipping

Shipping options may be necessary if your products require shipping. If any items in the cart require shipping, these steps cannot be skipped. These settings are configured for store products on a product-by-product basis. Donations and memberships cannot be shipped. If none of your products in a cart require shipping, you can omit this section.

If you add an item to a shopping cart that requires shipping, you must include shipping-related details as part of the transaction. These methods must be called after all items have been added to the shopping cart. These include:

4a. Add a Shipping Method to the Shopping Cart

After retriving the available shipping methods from listShippingMethods, use this request to select one for this transaction.

4b. Add a Shipping Address to the Shopping Cart

You must specify a shipping address for this purchase. This is separate from an account’s address, and must be supplied for any order that has items that require shipping.

5. Retrieve the Shopping Cart Summary

This request can be called at any time after a shopping cart has been created. It will display all information that has been added to a shopping card, such as the products inside, the customer, and the shipping information. It is necessary to call this method immediately before checkout because it will include the final purchase price. The final purchase price must match the payment amount you include with the Checkout method.

6. Checkout

The checkout method processes a payment for a shopping cart and completes the transaction. Once a shopping cart has been successfully checked out, you can no longer modify its contents. To complete this step, you will need a valid shopping cart with all required information added.

Once completed successfully, your shopping cart becomes an order. You will receive an Order Id as part of the server response. With this Order Id, you will be able to search for orders based on date range or account Id, retrieve specific details about this order, or retrieve a PDF receipt.