API

Cartfunnel REST API

Cartfunnel’s REST API follows RESTful conventions and utilizes the four commonly accepted request verbs for managing resources:

  • GET
  • POST
  • PATCH
  • DELETE

The format in which requests are received and responses are returned is in application/json or text/json.

Getting started

All requests should be made to the following endpoint:

https://api.cartfunnel.net/v1

Every request needs to be authenticated by adding the following headers into your request:

  • X-CARTFUNNEL-ACCOUNT
  • X-CARTFUNNEL-API-SECRET

X-CARTFUNNEL-ACCOUNT should be set as the value of your Cartfunnel subdomain. For example, if your Cartfunnel account lives at https://myshop.cartfunnel.net, the value should be “myshop”.

X-CARTFUNNEL-API-SECRET is a generated API secret that you create within the Cartfunnel dashboard. Go to Integrations and click on API, and then click on Create API secret.

You can customize the permission level for each individual API secret on the next page.

Remember: Do not share your API secret with any developer or third-party application that you do not trust. Treat your API secret safe!

API terminology

For those of you who are familiar with REST APIs, the following terminology should be familiar.

Each endpoint is what we call a Resource. For example, the Customer resource lives at /customers. The Product resource is found at /products.

An API call is referred to as a request. Each request must be made with a GET, POST, PATCH, or DELETE. These are called verbs. A GET request is made to retrieve a resource. A POST or a PATCH request is made to create or update a resource. Finally, a DELETE request is for destroying a resource. Not all verbs are available for all resources.

Handling errors

Successful API calls will return a 2xx HTTP return code. Note that a 200-level code is returned even in instances where an object is not saved, such as during a POST or PATCH request. To enable you to be able to quickly identify improperly saved objects, please examine the following:

  • Each resource object will have a “persisted” attribute. If it is set to “true”, that means the new object is saved. If it is set to “false”, it is not saved.
  • When saving a new or existing object, check for the “errors” attribute. Problems with saving the object will result in the presence of the “errors” attribute, which is an array of error messages. Successful saves will not return an “errors” attribute in the object.

Unsuccessful API calls will return a 403 code. Examples of unsuccessful calls include:

  • Wrong authentication credentials
  • API calls that are outside the permitted scopes (as set in the dashboard)

Customers resource

The Customers resource enables you to:

  • List all your customers
  • View the details of a single customer
  • Create a new customer
  • Update an existing customer

A customer object looks like this:

{
"id": 1,
"email": "[email protected]",
"created_at": "2018-12-04T23:29:37.406-05:00",
"updated_at": "2018-12-04T23:29:37.406-05:00",
"accepts_marketing": "true",
"first_name": "Joe",
"last_name": "El",
"note": "Special user",
"orders_count": 3,
"total_spent_cents": 100000,
"tax_exempt": "false",
"subscriptions_count": 1,
"last_order_id": 3200291,
"persisted": "true"
}

Properties

AttributeTypeNotes
emailstringrequired, on new records only
first_namestringoptional
last_namestringoptional
notestringoptional
tax_exemptbooleandefaults to false
accepts_marketingbooleandefaults to false
tag_liststringoptional, comma delimited string

GET /customers.json

Calling this endpoint will return an array of customer objects with a limit of 100 customer records at a time. Append an extra “page” parameter to this endpoint to paginate through your records:

https://api.cartfunnel.net/v1/customers.json?page=2

GET /customers/:id.json

This endpoint retrieves a single customer object. Replace the “:id” parameter with the ID of the customer record.

Example request:

https://api.cartfunnel.net/v1/customers/92310.json

The above call will retrieve the customer record with the ID of 92310, if the customer exists within the specified Cartfunnel account.

POST /customers.json

To create a new customer, you must supply at the very minimum an email address and creating a POST request to the above endpoint with

Example request:

https://api.cartfunnel.net/v1/customers.json

The request body:

{
"customer": {
"email": "[email protected]",
"first_name": "Anna",
"last_name": "Benning"
}
}

A successful response might look like this:

{
"id": 32199,
"email": "[email protected]",
"created_at": "2019-02-04T23:29:37.406-05:00",
"updated_at": "2019-02-04T23:29:37.406-05:00",
"accepts_marketing": "false",
"first_name": "Anna",
"last_name": "Benning",
"note": "",
"orders_count": 0,
"total_spent_cents": 0,
"tax_exempt": "false",
"subscriptions_count": 0,
"last_order_id": "null",
"persisted": "true"
}

You may notice that there are other attributes in the object, such as created_at and orders_count. Certain attributes are not modifiable and are automatically generated by Cartfunnel.

PATCH /customers/:id.json

To update a customer record, you can make a request to the above endpoint.

Example request:

https://api.cartfunnel.net/v1/customers.json

The request body:

{
"customer": {
"first_name": "Anna",
"last_name": "Jules"
}
}

Should the request be saved successfully, you will request a return JSON object without an errors attribute.

If an error occurs, you might see the following response:

{
"id": 32199,
"email": "[email protected]",
"created_at": "2019-02-04T23:29:37.406-05:00",
"updated_at": "2019-02-10T23:29:37.406-05:00",
"accepts_marketing": "false",
"first_name": "Anna",
"last_name": "Jules",
"note": "",
"orders_count": 0,
"total_spent_cents": 0,
"tax_exempt": "false",
"subscriptions_count": 0,
"last_order_id": "null",
"persisted": "true",
"errors": ["An error has occurred"]
}

You should check the return object to see if an “errors” attribute exists. If it exists, the record was not saved.

Customers — Addresses resource

The documentation for this resource is not yet available.

Customers — Subscriptions resource

The documentation for this resource is not yet available.

Products resource

The documentation for this resource is not yet available.

Orders resource

The documentation for this resource is not yet available.

This website uses cookies to ensure you get the best experience on our website.

Split payments into cycles

Accept deposit payments

Configure your products to receive a set deposit. Cartfunnel will retain the customer’s billing information so you could bill the balance later.

Pre and Post payment upsells
Set upsell conditions

One click upsells

Show the right upsell offer during the checkout flow. Offer upsells both before and after payment has been made.

Recurring billing in Shopify
Charge later

Recurring billing done right.

Add subscriptions and recurring billing to your existing Shopify store. Use our built-in customer portal to allow customers manage their billing.

HTML Liquid templates
Liquid code

Customizable checkout pages

Easily make changes to your checkout pages to maximize for conversion. Change your font, colors, agree to terms, and more.