Skill Level: Advanced.

There are a few situations where FoxyCart's “cart” functionality isn't needed. Though an uncommon situation, some examples include:

• Integrations where a persistent cart already exists, and where Foxy is replacing just the checkout flow (to offload PCI compliance burdens, most frequently).
• Custom situations where a cart doesn't exist, but where custom validation or other advanced requirements may require your own application logic in front of the Foxy-powered cart.
• Sites or services where products are configured at the time of purchase, and a customer shouldn't ever be able to directly interact with the cart. (Note that this is generally possible in a simpler way than outlined on this page.)

Luckily, Foxy is flexible enough to handle even some of the most customized requirements you could throw at it. On this page, we'll discuss the basic approach you might take for integrations like this. First, though, a few important notes.

When we use the term “cart”, we can mean two different things:

1. The visual display of the cart that a customer usually sees. This would include things like the names, details, images, prices, and quantities of the items a customer is purchasing.
2. The underlying data behind the visual display.

Though you can avoid the first, Foxy will always require the “cart” to exist for a transaction. This ensures Foxy can provide all of these details to the payment systems (ie. Authorize.net, Stripe, PayPal, Amazon), and also that taxes and other functionality works as expected. In other words, you can't simply tell Foxy “Charge this customer $100”. Instead, you must supply what constitutes that $100 charge.

Note that you can entirely bypass the cart (and take customers straight to the checkout) without doing anything on this page. Simply use the cart=checkout parameter described on the cheat sheet to skip the cart step entirely.

Though you can self-host a custom cart if desired, you must use Foxy's hosted checkout (located at /checkout at your custom Foxy domain). This ensures the bulk of PCI compliance is shifted from you to us.

A normal Foxy integration would look like this:

1. Your website has “add to cart” or “buy now” (or “donate now”, etc.) buttons (links or forms). These buttons are a or form pointing to the /cart endpoint of your FoxyCart account.
2. A customer clicks one of those buttons. The browser submits a GET or POST request to the Foxy /cart endpoint. The cart is then displayed. By default, this would be the “sidecart” that slides in from the right, but it could also direct the customer to a new webpage showing only the cart, or it could take the customer directly to the checkout (which displays the cart in the right column).
3. The customer lands on the Foxy-hosted checkout page. The customer completes the page and clicks to submit their payment.
4. The payment processes successfully and lands on the Foxy-hosted receipt page, showing what they just purchased and relevant transaction IDs.

Let's imagine that you've already got your own cart functionality, however, and your “add to cart” buttons are already pointing to your own system. You want to continue using that functionality, but to have Foxy take over at the checkout portion. Here's how your integration would differ from the approach above:

1. Your website's “add to cart” buttons point to your ownsystem, and not to your store's /cart endpoint.
2. Any cart that is displayed (prior to the checkout) is entirely handled by your system.
3. When the customer indicates they'd like to pay, your system…
   1. Creates a cart in Foxy (using the Foxy API), based on the items in your own system's cart for that user.
   2. Redirects the customer to the /checkout URL with the appropriate session ID, and optionally with a SSO token if the customer is already authenticated.
4. Once the customer completes the checkout on the Foxy-hosted checkout page, the customer can…
   • Land on the Foxy-hosted /receipt, or
   • The Foxy-hosted /receipt can immediately redirect the customer to a URI of your choosing, optionally with a “reverse” (or outgoing) SSO token.
   • Your system can optionally create or sync the customer's account so their info entered in Foxy is up to date with the info in your system (including their hashed password).

There are a few moving pieces here: the cart; incoming SSO (single sign-on); outgoing/reverse SSO; and synching customer records. We'll cover each below.

Foxy provides two different methods of interacting with the cart. The /cart endpoint, and the hypermedia API.

The most straightforward approach is to use the same /cart endpoint that the clientside requests hit, using the output=json parameter. There is no authentication with this approach (though you can use the link/form signing functionality to lock things down), so this approach is generally going to be easier to work with for most users.

This approach works just like normal cart requests from the client, except with the json output flag, Foxy will respond with valid JSON that's easy for you to parse and act upon. For example, if you load up this URI (replace the YOURDOMAIN as appropriate, and disable the hmac link/form signing in your store settings to test)…

curl https://YOURDOMAIN.foxycart.com/cart\?name\=Cool%20Example\&price\=10\&color\=red\&code\=sku123\&output\=json

You'll see JSON like this:

{"locale_info":{"decimal_point":".","thousands_sep":"","int_curr_symbol":"USD ","currency_symbol":"$","mon_decimal_point":".","mon_thousands_sep":",","positive_sign":"","negative_sign":"-","int_frac_digits":2,"frac_digits":2,"p_cs_precedes":1,"p_sep_by_space":0,"n_cs_precedes":1,"n_sep_by_space":0,"p_sign_posn":1,"n_sign_posn":1,"grouping":[],"mon_grouping":[3,3],"int_p_sep_by_space":1,"int_n_sep_by_space":1},"locale_code":"en_US","weight_uom":"LBS","context":"cart","store_id":41795,"transaction_id":1109984022,"items":[{"item_number":1,"shipto":"","id":71966542,"name":"Cool Example"

The above response is truncated, but the full response includes everything necessary to understand and work with the cart. One of the most important elements of the response is the session_id value. If you’d like to modify that cart, you’ll need to pass through the session ID (like &fcsid=abc123xyzetc). FoxyCart will create a new session if no fcsid value is passed through with the request.

If you're building a deeper integration, you may already be working with our Hypermedia REST API. For the purposes of this page, we'll assume basic working knowledge of the hAPI (including authentication via OAuth 2.0 and how to navigate using the hypermedia link relationships). This hAPI approach provides considerably more functionality,