Using a Cart

Using a cart is a multi-step process. You'll need to do the following things in order:

  • Create a Cart
  • You can do the following in any order:
    • Add Items To Cart
    • Attach A Shipping Address
    • Attach A Shipping Method
    • Attach A User
  • Checkout

    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.

    • Pay With Shop Credit
    • Pay With Invoice
    • Pay With A Credit Card

    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.

Cart Properties

Each cart has the following properties and is accessed via /api/cart. Complete details in OrderProperties and OrderItemProperties.

id

The unique id for this cart. It will never change.

wing_object_type

cart.

name

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.

user_id

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.

items

An array of items that are in the cart. See "Cart Related Objects" below for details.

shipping_address_id

An Address id. The unique id of an address. See Address for details on creating an address.

shipping_address

A hash of address properties associated with the shipping_address_id. See "Cart Related Objects" below for details.

shipping_method

The shipping mechanism that will be used to transport the cart to the purchaser. Defaults to USPS Priority. See Cart Options below for details.

shipping_cost

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.

subtotal

The cost of all the items attached to the cart before taxes, shop credit, and shipping are applied.

taxes

The amount of taxes to be paid to purchase this cart. Will always be zero until a shipping address has been specified.

insured

A boolean indicating whether this order is marked to be insured for damages. Defaults to 1.

insurance_cost

The cost associated with flipping the insured bit.

urgent

A boolean indicating whether this order is marked for expedited production. Defaults to 0.

urgent_fee

The cost associated with flipping the urgent bit.

total

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.

payment_method

The method used to pay for the cart. Defaults to Credit Card. See "Cart Options" below for details.

payment_transaction_id

If an attempt has been made to pay for this cart then the id returned from the payment gateway will be logged here.

payment_status

If an attempt has been made to pay for this cart then the status code returned from the payment gateway will be logged here.

payment_message

If an attempt has been made to pay for this cart then the message returned from the payment gateway will be logged here.

ip_address

The IP address of the user at the time of cart creation.

date_created

A date when the cart was created.

date_updated

A date when the cart's account was last updated.

Relationships

See "Relationships" in Intro for details.

items

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.

Related Objects

See "Related Objects" in Intro for details.

user

The user attached to this cart, if any. Will return:

 {
    "shop_credit" : "0.00",
    "username" : "andy",
    "id" : "xxx",
    ...
 }
shipping_address

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"
 }

Cart Methods

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

Cart Options

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.

Create Cart

 POST /api/cart
api_key_id

See APIKey. Required.

name

Optional.

shipping_address_id

Optional. Will be required before checkout.

Returns:

 {
   "id" : "xxx",
   "cartname" : "andy",
   ...
 }

Update Cart

PUT /api/cart/xxx

See Create Cart for details. Can only be done by an admin or the cart owner itself.

Delete Cart

DELETE /api/cart/xxx

session_id

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
 }

Fetch Cart

GET /api/cart/xxx

session_id

Optional. The unique session id provided by a Session method.

Can by done by anybody.

Returns:

 {
   "id" : "xxx",
   ...
 }

Add Items To Cart

 POST /api/cart/xxx/sku/xxx

Allows you to add a Sku to the cart.

quantity

Optional. Defaults to 0. Adds or subtracts items to or from the cart depending on whether this number is positive or negative.

Adjust Items In Cart

PUT /api/cart/xxx/sku/xxx

Allows you to adjust the quantity of this Sku in the cart.

quantity

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.

Attach A Shipping Address

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.

Get Shipping Method Options

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.

Attach A User

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.

session_id

A session id as created by Session.

email

An email address of the user checking out. This only works if the user is not already in the system.

Pay With Shop Credit

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.

Pay With Invoice

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.

po_number

Purchase order number. Any characters up to 30 digits. Required.

Pay With Credit Card

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.

card_number

The credit card number.

expiration_month

The month that the card expires.

expiration_year

The year that the card expires.

cvv2

The three digit code on the back of the card, or the 4 digit code on the front of an American Express card.

Convert To A Wishlist

POST /api/cart/xxx/wishlist

Converts this cart to a Wishlist.

Fetch List of Cart Items

 GET /api/cart/xxx/items

Returns:

 {
   "items" : [
         {
            "quantity" : "1",
            "name" : "Prison Break",
            "price_each" : "0.8900",
            "id" : "563C57FE-47F0-11E2-836F-50F9C28E391D",
            ...
         }
         ...
    ],
    "paging" : {}
   }
^ Back to Top ^