Cartfunnel Cart AJAX/JSON API

This documentation is a work in progress. Please contact [email protected] if you have any questions.

Cartfunnel’s Cart Ajax/JSON API allows merchants to modify a customer’s shopping cart before the checkout process begins as well as during the checkout process.

Common use cases include:

Adding items to the cart
Removing items from the cart
Updating item quantity
Adding subscriptions to the cart
Removing subscriptions from the cart
Updating item subscription quantity
Clearing the cart
Storing referral (eg. affiliate) information

We will describe the applicable endpoints below.

Important to know

You should expect all responses to be of the application/json content type. None of the calls below require you to send data/body within your request.

For security purposes, you cannot alter a cart (referenced by a specific token) once that cart has completed the checkout.

Setting up your shopping cart token

Each shopping cart has an unique cart token. You must get this token from Cartfunnel’s servers before you perform any functions on a customer’s shopping cart. This token should be stored within a customer’s browser cookie.

Tip: Store the customer’s cart token in a cookie. Check for its existence, and if it doesn’t exist, create a new token via the following endpoint.

For the purpose of our discussion here, we will assume that your shopping cart lives at https://myshop.cartfunnel.net. You may substitute this domain with your custom domain if you have that set up.

For the example below, the endpoint will be at https://myshop.cartfunnel.net/api/cart/create.json. We will omit the base URL for the purpose of this documentation.

Step 1: Perform a GET request to retrieve a new token with a GET request:

/api/cart/create.json

Cartfunnel will return a Cart JSON object, such as the one below:

{
  token: "481089478cb863e85702...",
  line_items: [],
  total_line_items: 0,
  subtotal: 0,
  subtotal_cents: 0,
  formatted_subtotal: "$0.00"
}

The value is under the JSON key of “token”, as illustrated in the above code snippet.

All requests to Cartfunnel’s Cart AJAX/JSON API will now use that token in order to perform any functions on this token.

Note: Carts are automatically destroyed after 2 weeks of inactivity and are considered abandoned after 60 minutes of inactivity. In your code to check for the validity of a token, remember to set the cookies accordingly and to check with Cartfunnel’s servers for the existence of a cart.

Verifying a shopping cart token

In certain cases, you will want to verify that a shopping cart token exists. Use the following endpoint with a GET request.

/api/cart/{{ token }}/verify.json

Remember to replace the {{ token }} with the actual token.

If a Cart is not found corresponding to the token you send, a new token will be returned to you in the same request in order to minimize the amount of back and forth traffic between your website and Cartfunnel’s.

Retrieving a shopping cart

You can retrieve a shopping cart and its line items by calling the following endpoint with a GET request:

/api/cart/{{ token }}.json

This endpoint will not generate a new token should the one you send not already exist.

Sending customers to their cart

Once the customer is ready to proceed to the checkout, you can send the customer directly to the shopping cart by redirecting the customer to the following URL:

/continue/{{ token }}

Note that this is an non-AJAX call (ie. redirect the browser’s location bar) and should be called with a regular GET request.

Adding a product to the cart

To add an item to a shopping cart, call the following endpoint with a POST request:

/api/cart/{{ token }}/add/{{ variant_id }}/quantity/{{ quantity }}.json

Replace {{ token }} with the cart token, {{ variant_id }} with the variant ID of the product variant that you’re adding, and {{ quantity }} with the quantity.

Removing a product from the cart

To remove an item from a shopping cart, call the following endpoint with a POST request:

/api/cart/{{ token }}/remove/{{ variant_id }}.json

Again, replace {{ token }} with the cart token and {{ variant_id }} with the variant ID of the product variant.

Updating a product in a cart

In some cases, you will want to update a product quantity. You can call the following endpoint with a POST request:

/api/cart/{{ token }}/update/{{ variant_id }}/quantity/{{ quantity }}.json

Replace {{ token }} with the cart token, {{ variant_id }} with the variant ID of the product variant that you’re adding, and {{ quantity }} with the quantity.

Adding subscriptions to the cart

Each product can have multiple subscription settings. To add a product with subscription settings, call the following with a POST request:

/api/cart/{{ token }}/add/{{ variantID }}/quantity/{{ quantity }}/sub/{{ subscription_id }}.json

Replace {{ token }} with the cart token, {{ variant_id }} with the variant ID of the product variant that you’re adding, the {{ quantity }} with the quantity, and {{ subscription_id }} with the ID of the subscription setting.

Removing subscriptions from the cart

To remove a product with subscription settings, call the following with a POST request:

/api/cart/{{ token }}/remove/{{ variantID }}/sub/{{ subscription_id }}.json

Replace {{ token }} with the cart token, {{ variant_id }} with the variant ID of the product variant that you’re adding, and {{ subscription_id }} with the ID of the subscription setting.

Updating subscription

To update a product with subscription settings, call the following with a POST request:

/api/cart/{{ token }}/update/{{ variantID }}/quantity/{{ quantity }}/sub/{{ subscription_id }}.json

Replace {{ token }} with the cart token, {{ variant_id }} with the variant ID of the product variant that you’re adding, {{ quantity }} with the updated quantity, and {{ subscription_id }} with the ID of the subscription setting.

Clearing a shopping cart

The following endpoint will clear all line items from a shopping cart by calling it with a POST request:

/api/cart/{{ token }}/clear.json

Replace {{ token }} with the cart token.

Storing a referrer (eg. affiliate code)

If you need to store a referrer’s code and associate it with a shopping cart, call the following endpoint with a POST request:

/api/cart/{{ token }}/referrer.json

Note: Because affiliate tracking scripts may not have cross domain functionality, this endpoint comes in handy when you need to assign proper attribution to referral links. Many affiliate companies store an unique referrer code for each referral. This code should be assigned to this endpoint so that you can retrieve it later and on the thank you (ie. conversion) page hosted on Cartfunnel.

Replace {{ token }} with the cart token.