UltraCart REST Auto Responder API

Owned by Perry Tew
Last updated: Jun 06, 2016
3 min read

Note: This is for the UltraCart internal Auto Responder (Home → Marketing → AutoResponders).

This API does not interact with third-party external auto responders such as GetResponse, etc.

This API is not complete. It is not yet scheduled for development. A single API call was created (subscribe) to meet the needs of merchants. Thanks.

 

 

Introduction (Things you'll wish you read first)

The UltraCart REST API aims to be a lightweight protocol for tying a checkout page(s) to the UltraCart back end.

 

 

Every call needs a merchant id (our merchant id is DEMO). We need to know who you are. There are three ways to provide the merchant id to the server:

  1. Query Parameter: _mid=DEMO
  2. HTTP Header: 'X-UC-Merchant-Id': 'DEMO'
  3. Cookie named UltraCartMerchantId

Most of the examples below use the http header since it's easy to use with jQuery. If you wished to do it for all your ajax calls, you could execute this javascript:

jQuery.ajaxSetup({ cache: false, headers: {'X-UC-Merchant-Id': 'DEMO', "cache-control": "no-cache"});

However, that makes each call less atomic (and jQuery doesn't recommend it). Still, it's an option and may work well with your site.

If you receive an error "Missing Merchant ID", you've forgotten to do one of the above.

 

Now, in case you're wondering why the three methods use different names...

  1. We made the query parameter as short as possible to keep the urls as short as possible. We used an underscore to denote "meta data" to the call.
  2. We follow common practices for naming custom http headers. While the X- prefix is officially out of vogue, we still think it looks cool.
  3. The cookie 'UltraCartMerchantId' is used in hundred of existing UltraCart checkout pages. So it made sense to stick with that cookie name.

 

 

When something doesn't work or you get an error, open your browser console and view the headers. Look for the error.

then fix it.

Can't? Then get on github.com. Ask for help.

 

 

Object Model

There are no objects specific to the Auto Responder API yet.

 

Auto Responder REST API

 

 

/rest/autoresponder/subscribe

Method
GET
Comments
Descriptionenrolls a customer into a campaign

 

Cookies

none

 
Path Parametersnone

 

Query Parameters

_mid

campaignOid

email

name

Merchant ID ( this can also be passed as a cookie or header – see notes in the Introduction) 

Integer, campaign id. You may find this on the main Auto Responder page in the Campaigns table. It's the first column.

Email of customer to enroll

Optional first and last name. If this is null, the email is inserted in this field also

Headers

none

 
Receives Jsonnone 
Returns JsonNone. Plain Text

Here are the various return messages:

success. re-enrolled.

success

failure. already enrolled and no re-enrollment.

failure. customer is enrolled and in-progress. nothing done.

 

 

Discussion:

If the customer does not exist in the campaign and everything works, success is returned.

If the customer exists, and in a finished state, and the campaign is set to re-enroll, then the customer is re-enrolled and success. re-enrolled. is returned.

If the customer exists and the campaign is not configured for re-enrollment, failure. already enrolled and no re-enrollment. is returned.

If the customer exists and re-enrollment is turned on, yet the customer is in progress, nothing is done and

failure. customer is enrolled and in-progress. nothing done.

 is returned.


It's important to realize the none of the above conditions are bad. Each message above is indicative of a healthy auto responder. success/failure pertains to enroll, but regards business logic.

 

If there is a server error, a 500 status code will return. If there is invalid or missing parameters, a 400 status code will return. Those are the issues you need to worry about.

 

Example:

http://secure.ultracart.com/rest/autoresponder/subscribe?_mid=DEMO&campaignOid=1&displayName=Test+User&email=test@test.com