Hello World

Below is a simple walk-through to show you how quickly you can accomplish complex commerce tasks in a few lines of code.

Before we get started, let's get a few things set up:

  • If you haven't done so yet, create a Comecero account. Don't worry, no contracts, credit cards or commitments are required.
  • Create at least one product in your test account. Just sign into your account, toggle to "Test" mode (upper right of the screen), then click Store> Products, click "Add New". Make note of the product_id.
  • Create a Limited test token. From your account, go to Developer> API Tokens, click "Add New", select "Limited Token" and choose Test mode. Click to create the new token. Set the token aside for reference in a moment. You can read more about tokens and authentication if you'd like.

OK, now let's do a little coding. We'll keep this pretty simple.

To run your test script, you'll need a local web server. You don't need any particular web server - your script will just be HTML and JavaScript.

Important note! If you are running your page locally under anything other than localhost or 127.0.0.1, you'll need to set the hostname or IP address as an approved CORS origin in your account or your test script won't be able to connect to the API. For example, if you load the script locally under http://localdevelopment.com, just add that as a CORS origin under Settings> General> CORS Allowed Origins. Read more about CORS.

Don't want to walk through this tutorial step by step? No problem, you can download the final HTML document created in this tutorial and read the comments in the source code.

Create a new file somewhere in your web server directory. Let's call it index.html. Let's put the following code in our file:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta charset="utf-8" />
    <title>Hello World</title>
    <!-- Load up jQuery -->
    <script src="//ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js"></script>
</head>

Hello World!

<script>
// Just a placeholder for now.
</script>

<body>

So far so good. Now let's write a few JavaScript functions that we'll use in our page. We'll paste these between the <script></script> tags in our HTML page. The first function is just a helper to write messages to the browser window so we can see what's happening as the script runs. The second is simple wrapper around the jQuery ajax function to make it easy to send data to the API.

// This is just a function that we use to write messages to the screen as our script runs.
var writeLog = function (message) {
    $("body").append("<p>" + message + "</p>");
}

// This is a function that we use to post data to the API using jQuery.
var sendPost = function (url, token, data, onSuccess, onError) {
    $.ajax({
        url: url,
        beforeSend: function (xhr) {
            // We add our token to the request header
            xhr.setRequestHeader("Authorization", "Bearer " + token);
        },
        method: 'POST',
        dataType: 'json',
        data: JSON.stringify(data),
        success: function (response) {
            // Call the onSuccess function, if supplied.
            if (onSuccess) {
                onSuccess(response);
            }
        },
        error: function (error) {
            // Call the onError function, if supplied.
            if (onError) {
                onError(error.responseJSON.error);
            }
        }
    });
}

Now we are going to define the token that we'll use to call the API. Note that you'd never want to hard-code a Limited token in an app that's intended for production use. But this will keep our demo simple.

// Define your token.
// In a real app, you'd make a simple API call to get a token for a new user and store it in a cookie for that user.
// We'll hard-code a test token to keep it simple. You can create a test token from within your account under Developer> API Tokens.
var token = "limited.test.6A2qnDM88FfYMOsIaFhg89NwkXG5yhAfEbYdyFc3b3A.1456630515.6f98388bfa";

OK - now it's time to create our cart! There are a lot more options we can define if we need. See the API Explorer for details. Again, just paste this snippet below our previous code.

// Create the cart.
var cart = {
    items: []
};             

// Create an item to put in the cart.
var item = {
    product_id: "1.test", // This is the product_id from the product we created earlier.
    quantity: 1
};

// Add the item to your cart.
cart.items.push(item);

// Now let's create a customer. Choose carefully! An email confirmation will actually be sent to the address you supply!
// We don't have to create the customer now - we could create the cart now and add the customer to it later.
var customer = {
    name: "John Doe",
    email: "john@example.com",
    billing_address: {
        address: "123 Main St.",
        city: "San Francisco",
        postal_code: "94101",
        country: "US"
    }
}

// Add the customer to the cart.
cart.customer = customer;

Alright - we've got everything configured, now we're ready to send the cart to the API. If the cart creation is successful, we'll submit a payment for it. We'll output our status to the screen as we go. Just paste this code below our previous.

writeLog("Preparing to create the cart.");

// Send the cart to the API.
sendPost("https://api.comecero.com/api/v1/carts", token, cart, function (cartResponse) {

    writeLog("Nice! The cart has been created with a total of " + cartResponse.total);

    // Create a payment method
    var paymentMethod = {
        type: "credit_card",
        data: {
            number: "4444555566661111", // Use 4444555566669999 to simulate a declined payment
            exp_month: 12,
            exp_year: 21,
            cvv: "123"
        }
    };

    // Create a payment. We don't need to supply anything other than the payment method.
    var payment = {
        payment_method: paymentMethod
    }

    writeLog("Preparing to make the payment.");

    // Send the payment to the API.
    sendPost("https://api.comecero.com/api/v1/carts/" + cartResponse.cart_id + "/payments", token, payment, function (paymentResponse) {

        // Great! The payment was successful.
        writeLog("Congrats! You have just completed a payment in the amount of " + paymentResponse.total + ". Login to your account to see the full details.");

    }, function (error) {

        // Something happened and the payment failed. Let's see what the error was.
        writeLog("Oh no! There was a problem processing the payment: " + error.message);

    });

}, function (error) {

    // Looks like we had a problem creating the cart.
    writeLog("Whoops! There was a problem creating the cart: " + error.message);

});

OK - we're ready to run the script. Just load it in your URL address bar and you can see the output. After it's complete, you can sign into your account and see the results. Take a look under Sales> Carts, Sales> Orders and Sales> Payments to see more details.

Well done! You can download a copy of the page we created here.

Of course, there's a number of things we'd do in a production-ready app that we didn't do here, like placing the JavaScript in a dedicated file instead of directly in the document. But hopefully this exercise allows you to start thinking about how rapidly you can create competely custom ecommerce solutions.