Using a cart is a multi-step process. You'll need to do the following things in order:
When you successfully attach a payment method to a cart you'll convert it into a Receipt. It is at this point that shop credit will be deducted from the order before sending the request to the payment provider.
Another way to checkout is to hand off the checkout process to our web interface. It is recommended that you skip attaching a user and addresses to this cart if you use this method. To do this redirect the user to:
https://www.thegamecrafter.com/cart/XXX
Or:
https://www.thegamecrafter.com/checkout/cart/XXX
Replace XXX with the cart_id of the cart you'd like them to check out with. The first URI will bring them to the cart so they can view, modify, or continue shopping. The second URI will bring them directly to the checkout process.
Each cart has the following properties and is accessed via /api/cart. Complete details in OrderProperties and OrderItemProperties.
The unique id for this cart. It will never change.
cart.
A label to identify an cart. This is useful if you're going to allow multiple carts open at the same time, or if you want to name wishlists.
A User id. If specified, the unique id of the user that controls this cart. Once a user has been attached to an cart, it cannot be viewed or manipulated except by passing a working session id for that user. See Cart Options below for details. Defaults to Cart.
An array of items that are in the cart. See "Cart Related Objects" below for details.
An Address id. The unique id of an address. See Address for details on creating an address.
A hash of address properties associated with the shipping_address_id. See "Cart Related Objects" below for details.
The shipping mechanism that will be used to transport the cart to the purchaser. Defaults to USPS Priority. See Cart Options below for details.
The amount added to the cart to account for the cost of shipping. This will be added to the cart once both a shipping address and a shipping method are known.
The cost of all the items attached to the cart before taxes, shop credit, and shipping are applied.
The amount of taxes to be paid to purchase this cart. Will always be zero until a shipping address has been specified.
A boolean indicating whether this order is marked to be insured for damages. Defaults to 1.
The cost associated with flipping the insured bit.
A boolean indicating whether this order is marked for expedited production. Defaults to 0.
The cost associated with flipping the urgent bit.
The total cost of the cart including taxes and shipping. If this is a Receipt it will also include the discount as a result of shop credit used.
The method used to pay for the cart. Defaults to Credit Card. See "Cart Options" below for details.
If an attempt has been made to pay for this cart then the id returned from the payment gateway will be logged here.
If an attempt has been made to pay for this cart then the status code returned from the payment gateway will be logged here.
If an attempt has been made to pay for this cart then the message returned from the payment gateway will be logged here.
The IP address of the user at the time of cart creation.
A date when the cart was created.
A date when the cart's account was last updated.
See "Relationships" in Intro for details.
An array of items that are currently placed in the cart
"items" : [
{
"quantity" : "1",
"name" : "Prison Break",
"price_each" : "0.8900",
"id" : "563C57FE-47F0-11E2-836F-50F9C28E391D"
...
}
...
]
Please see Game and Part for more details about what items may contain.
The user attached to this cart, if any.
See "Related Objects" in Intro for details.
The user attached to this cart, if any. Will return:
{
"shop_credit" : "0.00",
"username" : "andy",
"id" : "xxx",
...
}
The Address attached to the cart that the cart should be shipped to. Will return:
{
"id" : "xxx",
"user_id" : "xxx",
"name" : "Andy Dufresne",
"company" : "Shawshank Prison",
"address1" : "123 Prison Lane",
"address2" : "Shawshank Prison Library",
"city" : "Portland",
"state" : "Maine",
"postal_code" : "04101",
"country" : "US",
"phone_number" : "207-874-8300"
}
The methods used to fetch and manipulate carts.
NOTE: Any methods that require the cart ID in the URI, can have the ID ommitted to use the current cart stored in the browser's cookie. For example:
POST /api/cart/xxx/sku/xxx
Can become:
POST /api/cart//sku/xxx
Provides a list of the options that can be used to fill out various fields when creating or updating a cart.
GET /api/cart/_options
Returns:
{
"identity" : [...],
"shipping_method" : [...],
"_shipping_method" : {...},
}
NOTE: You can also get this data by adding _include_options=1 to the parameter list when fetching a cart.
POST /api/cart
See APIKey. Required.
Optional.
Optional. Will be required before checkout.
Returns:
{
"id" : "xxx",
"cartname" : "andy",
...
}
PUT /api/cart/xxx
See Create Cart for details. Can only be done by an admin or the cart owner itself.
DELETE /api/cart/xxx
Required. The unique session id provided by a Session method.
Can only be done by an admin or the cart owner itself.
Returns:
{
"success" : 1
}
GET /api/cart/xxx
Optional. The unique session id provided by a Session method.
Can by done by anybody.
Returns:
{
"id" : "xxx",
...
}
POST /api/cart/xxx/sku/xxx
Allows you to add a Sku to the cart.
Optional. Defaults to 0. Adds or subtracts items to or from the cart depending on whether this number is positive or negative.
PUT /api/cart/xxx/sku/xxx
Allows you to adjust the quantity of this Sku in the cart.
Optional. Defaults to 0. Sets the number of this item contained in the cart. Setting to 0 will remove it from the cart. If you set a quantity and the item isn't already in the cart it will be added.
Attaching a shipping address is easy using the Create Cart or Update Cart methods documented above as long as you already have an address. If you don't, then you'll need to create on using the Address service first.
Provides a list of shipping options the user can choose from. Every order will have a different set of options based upon the shipping destination, size, and weight of the order.
GET /api/cart/xxx/shipping-method-options
{
"Will Call" : {
"description" : "By selecting Will Call you agree to pick up your order at The Game Crafter facility in Madison, Wisconsin.",
"cost" : "0.00",
"handling_fee" : "0.00",
"insurance_rate" : "0",
"weight" : 20,
"number_of_parcels" : 1,
},
...
}
Description informs the user a little about this shipping option.
Cost is the cost the shipping provider is charging The Game Crafter, and therefore is passed along to the customer.
Handling Fee is the extra cost The Game Cafter applies. This covers the cost of the shipping box as well as any special paperwork that needs to be filled out to complete this shipping method.
Insurance rate is a decimal percentage that can be multiplied against the order subtotal to determine the shipping insurance cost.
Weight is the number of ounces the shipment will weigh.
Number of parcels is the total number of packages that will be used to send this shipment.
POST /api/cart/xxx/user
Before checkout you need to attach a user to the cart. This can either be done by attaching an authenticated session, or by simply specifying an email address.
{
"order" : { ... },
"session_id" : "xxx"
}
NOTE: The session_id returned here needs (or any session_id attached to the user_id attached to this cart) to be used on all subsequent interactions with the cart.
A session id as created by Session.
An email address of the user checking out. This only works if the user is not already in the system.
POST /api/cart/xxx/payment/shopcredit
A common way for people to use our API to private label their own processes is to use shop credit. Just keep your account stocked up with shop credit, and then when a customer checks out on your site, you can pay for it on ours using shop credit.
Returns a Receipt.
POST /api/cart/xxx/payment/invoice
Attaches an invoice to this cart to pay for the items in it. The invoice will be emailed you using terms set during pre-approval.
NOTE: You must be pre-approved to use this method.
Returns a Receipt.
Purchase order number. Any characters up to 30 digits. Required.
POST /api/cart/xxx/payment/creditcard
Attaches a credit card to this cart to pay for the items in it.
NOTE: You must be pre-approved to use this method.
Returns a Receipt.
The credit card number.
The month that the card expires.
The year that the card expires.
The three digit code on the back of the card, or the 4 digit code on the front of an American Express card.
POST /api/cart/xxx/wishlist
Converts this cart to a Wishlist.
GET /api/cart/xxx/items
Returns:
{
"items" : [
{
"quantity" : "1",
"name" : "Prison Break",
"price_each" : "0.8900",
"id" : "563C57FE-47F0-11E2-836F-50F9C28E391D",
...
}
...
],
"paging" : {}
}