Integrate your own cart with Foxy

Why you’d do this

A few common situations call for bypassing Foxy’s cart functionality:

• You already have a persistent cart in your own system, and want Foxy to take over just the checkout (commonly to offload PCI compliance).

• You need custom validation or other application logic in front of the Foxy-powered cart that doesn’t exist in a standard integration.

• Products are configured entirely at the time of purchase, and customers should never interact with the cart directly.

If you only want to skip the visual cart step and send customers straight to checkout, you don’t need any of this — just use the cart=checkout parameter on your add-to-cart links.

The cart: interaction versus underlying data

“Cart” can mean two different things: the visual display a customer normally sees (names, images, prices, quantities), and the underlying data behind that display. You can bypass the first, but Foxy always requires the underlying cart data to exist for a transaction — this is what gets passed to the payment gateway and what taxes and other functionality are calculated from. You can’t tell Foxy to simply charge a customer $100; you have to supply what makes up that $100.

You can self-host a custom cart, but you must still use Foxy’s hosted checkout (at /checkout on your Foxy domain) to shift the bulk of PCI compliance from you to Foxy.

How the integration differs from a standard flow

In a standard Foxy integration, add-to-cart buttons point directly to your store’s /cart endpoint, and the customer sees the Foxy-hosted cart, checkout, and receipt in sequence.

In this integration, your own cart handles everything up until checkout:

1. 1

   Add-to-cart buttons point to your own system, not to Foxy’s /cart endpoint.

2. 2

   Any cart display before checkout is handled entirely by your system.

3. 3

   When the customer is ready to pay, your system creates a cart in Foxy via the API (based on your own cart’s contents), then redirects the customer to /checkout with the appropriate session ID — optionally including an SSO token if the customer is already authenticated.

4. 4

   After checkout, the customer lands on the Foxy-hosted receipt, or is redirected to a URL of your choosing (optionally with an outgoing SSO token), and your system can sync the customer’s account.

Creating a cart server-side

Foxy provides two ways to create a cart from your server:

• The /cart endpoint — the same endpoint clientside requests hit, using output=json. No authentication is required by default (though you can lock it down with link/form signing), which makes it the easier option for most integrations.

• The Hypermedia API (hAPI) — POST to the /carts resource for more functionality and a consistent interface with the rest of your Foxy account. Retrieving and setting shipping rates isn’t currently supported through the hAPI, so you’ll need the /cart endpoint approach for that regardless of which method you use elsewhere.

See Interact with the cart server-side for the request details for both approaches.

Whichever approach you use, note the session_id (fcsid) returned — you’ll need to pass it on subsequent requests to modify the same cart, and to send the customer to checkout.

Redirecting the customer to checkout

Once the cart exists, send the customer to:

https://YOURDOMAIN.foxycart.com/cart?cart=checkout&fcsid=YOUR_FCSID_VALUE_HERE

Authenticating the customer (incoming SSO)

If your customer is already logged into your own system, use Foxy’s SSO functionality so they don’t have to log in again at checkout. If SSO is enabled on the store, a valid SSO auth token is required to load /checkout. Rather than redirecting through your SSO endpoint, a serverside integration can generate the token directly and send the customer straight to a URL like:

/checkout?fc_auth_token=AUTH_TOKEN&fcsid=SESSION_ID&fc_customer_id=CUSTOMER_ID&timestamp=TIMESTAMP

The customer must already exist in Foxy before you can generate a token for them — create them via the hAPI either on demand right before redirecting, or ahead of time.

Handling the customer after the transaction

By default, a completed checkout lands the customer on the Foxy-hosted /receipt page and triggers a webhook. For a serverside integration, you may want more control:

• Empty the receipt template so it never displays, and always redirect elsewhere.

• Keep the Foxy receipt for historical purposes (it’s linked from email receipts by default), but redirect immediately on first view.

• Keep the receipt visible with an optional “click here to continue” link.

To redirect on the initial view only, add logic to your template config using the first_receipt_display boolean check.

Outgoing SSO and user syncing

To log the customer into your own system automatically after their purchase — useful when customers are paying for access to content on your site — use outgoing (reverse) SSO. The approach mirrors incoming SSO. Foxy doesn’t support SAML by default, but it’s available for Enterprise customers, either implemented by Foxy or by using an intermediary script to bridge SAML to Foxy’s SSO approach.

Taxes, shipping, and coupons

This section uses the /cart endpoint rather than the hAPI, since shipping rate handling in particular isn’t currently supported there.

Taxes

To retrieve a tax estimate during your own checkout flow:

1. 1

   Create the cart and session as described above.

2. 2

   Attach a postal code to the session with a request such as:

   Copy Copied

   https://EXAMPLE.foxycart.com/v/2.0.0/api_json.php?city=San+Diego&region=CA&postal_code=92106&country=US&ThisAction=SaveCartContactInfo&fcsid=XXX&store_id=XXX
   

   A GetAddressByPostalCode action is also available to retrieve possible cities from an entered postal code, for basic address validation similar to the Foxy checkout.

3. 3

   Retrieve the tax information with a request to https://EXAMPLE.foxycart.com/cart?fcsid=XXX&output=json.

Note that the tax value may change once shipping is set, so you may need to repeat the retrieval step after setting shipping details.

Shipping

Shipping is normally handled automatically on checkout, but you can set shipping details (method name and price) without customer input.

Step 1: add the rate to the session.

https://EXAMPLE.foxycart.com/v/2.0.0/api_json.php?shipping_address_name=YYY&shipping_service_id=XXX&shipping_service_description=UPS+Ground&total_shipping=16.65&total_future_shipping=0&ThisAction=SaveShippingServiceInfo&fcsid=XXX&store_id=XXX

The YYY value is only needed for multiship addresses and can be left empty otherwise.

You can use Foxy’s built-in shipping rates — after retrieving a tax estimate, the cart’s JSON includes a shipping_results node whose values you can submit back using the pattern above — or pass through arbitrary shipping amounts, in which case shipping_service_id must be an integer greater than 10000.

If you’re pushing the transaction through entirely via the hAPI, this step is sufficient. If the customer will complete the transaction on the /checkout page themselves, continue to step 2.

Step 2: handle the shipping on checkout.

Even though the rate is already set, you also need to configure the custom shipping endpoint functionality so the checkout displays the same rate. If your endpoint returns the same details you set in step 1, the checkout loads with that rate already selected.

If the customer is authenticated via SSO, the rate may not be pre-selected — contact Foxy support to discuss options for these cases.

Coupons

Foxy doesn’t support passing through arbitrary discount amounts the way it does shipping, so applying your own discount logic takes a few more steps:

1. 1

   Calculate the discount amount in your own system.

2. 2

   Create a coupon code for that amount via the hAPI, with the appropriate display name and other details.

3. 3

   Add the coupon to the cart with a request like /cart?coupon=XXX, where XXX is the coupon code.

To remove a coupon, use /cart?cart=remove_coupon&coupon_code_id=XXX&fcsid=XXX. The coupon_code_id is available in the coupons node of the cart JSON for each applied coupon.

If your discount logic fits within Foxy’s existing functionality (quantity discounts, for example), it’s generally better to use Foxy’s built-in logic rather than generating a unique coupon code per transaction.

Notes

• This is an advanced integration path. Foxy’s support team can only offer full support for this approach to customers on API Premium or Single-Store Advanced plans.

• For the request details behind server-side cart creation itself, see Interact with the cart server-side.

• For a full list of cart parameters, see Cart parameters reference.