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.

Discounts resource

The Discounts resource enables you to:

  • List all your discount codes (current, active, and disabled)
  • View the details of a specific discount code
  • Add new discount code
  • Modify discount code
  • Disable discount code

A discount object looks like this:

{
   "id": 1, 
   "applied_pretax": true, 
   "applies_once": true, 
   "applies_once_per_customer": true, 
   "applies_to_id": 19882010, 
   "applies_to_resource": "product", 
   "apply_discount_to_resource_id": 19882010, 
   "code": "mydiscountcode", 
   "discount_type": "fixed_amount", 
   "ends_at": "2019-06-10T23:29:37.406-05:00", 
   "minimum_order_amount_cents": 0, 
   "starts_at": "2019-06-01T23:29:37.406-05:00", 
   "usage_limit": "null", 
   "value": 1000
 }

Properties

AttributeTypeNotes
applied_pretaxbooleandefaults to true
applies_oncebooleandefaults to false
applies_once_per_customerbooleandefaults to false
applies_to_idintegeroptional
applies_to_resourcestringdefaults to “store_wide”, options can be “store_wide” or “product”
apply_discount_to_resource_idintegeroptional
codestringrequired
discount_typestringdefaults to “fixed_amount”, can be “fixed_amount”, “percentage”, or “shipping”
ends_atdatetimerequired, UTC timestamp
minimum_order_amount_centsintegerdefaults to 1000 (eg. $10.00), number should be cents value
starts_atdatetimerequired, UTC timestamp
statusstringread only, either “enabled” or “disabled”
times_usedintegerread only
usage_limitintegeroptional, leave blank for unlimited
valueintegerrequired, discount value in cents

GET /discounts.json

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

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

GET /discounts/:id.json

Retrieve the record of a specific discount record as denoted by the ID.

Example request:

https://api.cartfunnel.net/v1/discounts/1601.json

The above request will retrieve the discount code with ID of 1601.

POST /discounts.json

Create a new discount code.

Example request:

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

The request body:

{
  "discount": {
    "applied_pretax": true, 
    "applies_once": true, 
    "applies_once_per_customer": true, 
    "code": "mydiscountcode", 
    "discount_type": "fixed_amount", 
    "ends_at": "2019-06-10T23:29:37.406-05:00", 
    "minimum_order_amount_cents": 0, 
    "starts_at": "2019-06-01T23:29:37.406-05:00", 
    "usage_limit": "null", 
    "value": 1000
  }
}

A successful response will return a full object such as illustrated above. Unsuccessful responses will return an error key.

PATCH /discounts/:id.json

You can call this endpoint to update an existing discount code. Note: In general, we do not recommend modifying a discount code once it has been released to your customers. It is better to create an entirely new discount code to ensure that settings are not changed midway through your marketing campaigns. For this reason, we recommend appending discount codes with the year or month it occurs to provide some level of uniqueness. Example: newyear2019 vs simply newyear.

Example request:

https://api.cartfunnel.net/v1/discounts/1601.json

The request body:

{
  "discount": {
    "applied_pretax": false
  }
}

DELETE /discounts/1601.json

Calling this endpoint will disable the discount. It will still be retrievable and can be re-enabled via the API.

Example request:

https://api.cartfunnel.net/v1/discounts/1601.json

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. The customer’s billing information is retained so you can bill them again 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.

We will build a recurring billing solution for your business that can adapt and change to whatever your business needs.

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.