Tutorial

Build a REST API Checkout with UltraCart

This tutorial walks a non-technical merchant (or novice developer) through building and launching a functioning REST-based checkout using UltraCart’s REST API v2 and PCI-compliant Hosted Fields for credit card entry.

Download the complete starter package (ZIP):

ultracart-rest-checkout-documentation-complete.zip

Overview

You’ll set up a working checkout that:

Creates/updates a cart via UltraCart REST
Collects billing/shipping details
Uses Hosted Fields so card data never touches your server
Submits the order and redirects to a thank-you page

Note: This starter package includes working files like index.html, thank-you.html, js/checkout.js, and css/checkout.css, plus a server/ script to generate a Browser Key.

Consider Visual Builder First (Recommended for Most Merchants)

Before investing in a custom code checkout, strongly consider building a customized checkout experience using the UltraCart StoreFront Visual Builder.

Why Visual Builder is often better long-term:

UltraCart manages the underlying codebase (you’re not maintaining a custom application)
Compiled StoreFront Themes are easier to maintain and less fragile than custom builds
Lower institutional knowledge risk (if a developer leaves, your checkout doesn’t become “mystery code”)
Faster iteration for merchandising/UI changes with far less technical overhead

If you still need a fully custom checkout (headless, embedded experience, special flows, etc.), continue with this REST checkout tutorial.

What You’ll Need

Accounts & access

An active UltraCart merchant account (admin access)

From UltraCart

A Simple Key (you will generate this in the UltraCart UI)
Your Merchant ID
Your Storefront domain (example: yourstore.ultracartstore.com)

On your computer

A folder where you can unzip files
Ability to run simple commands (copy/paste-friendly)

Software (one-time installs)

PHP (to run the Browser Key generator)
Composer (installs the UltraCart SDK used by the Browser Key generator)

[Image Placeholder: “Checklist” screenshot]

Steps

1) Download and unzip the starter package

Download: ultracart-rest-checkout-documentation-complete.zip
Unzip it somewhere easy to find, for example:
- Windows: C:\Users\YourName\ultracart-checkout
- Mac: ~/ultracart-checkout

You should see files like:

index.html
thank-you.html
js/checkout.js
css/checkout.css
server/setup-browser-key.php

[Image Placeholder: “Folder layout” screenshot]

2) Create your Simple Key in UltraCart

Log into UltraCart: https://secure.ultracart.com
Go to Configuration → API → Simple Keys
Click Add Simple Key
Name it something memorable (example: My Checkout Key)
Click Save
Copy the generated key and store it safely (example: in a text file named my-keys.txt)

Warning: Treat your Simple Key like a password. Do not put it in checkout.js or any public webpage.

[Image Placeholder: “Simple Keys screen”]

3) Install PHP (if needed)

Windows (common case)

Install PHP 8.x (Thread Safe) and make sure php -v works in Command Prompt.

Mac

Open Terminal and run:
```
php -v
```
If PHP isn’t found, install via Homebrew:
```
brew install php
```

[Image Placeholder: “php -v output”]

4) Install Composer

Windows

Install Composer from https://getcomposer.org/download/
Confirm it works:
```
composer -V
```

Mac

Run:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
sudo mv composer.phar /usr/local/bin/composer
php -r "unlink('composer-setup.php');"
composer -V

[Image Placeholder: “composer -V output”]

5) Generate a Browser Key (localhost testing)

A Browser Key is what your browser uses to call UltraCart REST endpoints safely. It is restricted by allowed referrers to prevent abuse.

Open a terminal/command prompt

Go into the server folder:

Windows:

cd C:\Users\YourName\ultracart-checkout\server

Mac:
```
cd ~/ultracart-checkout/server
```

Install dependencies:
```
composer install
```
Open server/setup-browser-key.php and set your Simple Key:
```
define('SIMPLE_KEY', 'YOUR_SIMPLE_KEY_HERE');
```

Make sure localhost referrers are allowed for testing:

$allowedReferrers = [
  'http://localhost:3000',
  'http://127.0.0.1:3000',
];

Run the script:
```
php setup-browser-key.php
```
Copy the Browser Key output and save it in my-keys.txt

[Image Placeholder: “Browser key generation output”]

6) Configure your checkout (`js/checkout.js`)

Open js/checkout.js and update the configuration block:

const UC_CONFIG = {
  browserKey: 'YOUR_BROWSER_KEY_HERE',
  storefront: 'yourstorefront.ultracartstore.com',
  merchantId: 'YOUR_MERCHANT_ID',
  returnUrl: window.location.origin + '/thank-you.html',
  errorReturnUrl: window.location.origin + '/index.html'
};

Set these values:

browserKey: the Browser Key from Step 5
storefront: your UltraCart storefront domain
merchantId: your UltraCart Merchant ID (Configuration → Account)
Leave the return URLs as-is for now

[Image Placeholder: “checkout.js config highlighted”]

7) Run the checkout locally

From your checkout folder (the one containing index.html):

Windows (simple local server using PHP)

cd C:\Users\YourName\ultracart-checkout
php -S localhost:3000

Mac (simple local server using Python)

cd ~/ultracart-checkout
python3 -m http.server 3000

Open your browser:

http://localhost:3000

NOTE: Review CORS for proper local host handing.

8) Add an item to the cart

In UltraCart, go to Items → View All Items
Copy an Item ID
Add it to the cart using a URL parameter:

http://localhost:3000?ADD=YOUR_ITEM_ID

You should see the item appear in the cart.

[Image Placeholder: “Cart with item added”]

9) Test placing an order

Fill out the billing (and shipping if applicable)
Enter a test card (your account/test environment rules apply)
Complete the purchase
Confirm you land on thank-you.html

[Image Placeholder: “Thank you page”]

Tip: If Hosted Fields do not load, jump to Troubleshooting → Hosted Fields / CORS.

10) Go live on your real domain (production)

When you’re ready to deploy, you must generate a new Browser Key that allows your real domain.

A) Update allowed referrers for production

Edit server/setup-browser-key.php:

$allowedReferrers = [
  'https://www.yourstore.com',
  'https://yourstore.com',
];

Run it again:

php setup-browser-key.php

Copy the new Browser Key.

B) Update `js/checkout.js`

Replace the old Browser Key with the new production key.

C) Upload files to your hosting

Upload:

index.html
thank-you.html
js/checkout.js
css/checkout.css

Note: You typically do not need to deploy the server/ folder once you’ve generated your Browser Key.

D) Confirm HTTPS

Your live checkout must be served over HTTPS.

Test:

https://www.yourstore.com/index.html?ADD=YOUR_ITEM_ID

[Image Placeholder: “Production domain test”]

Expected Outcome

By the end, you will have:

A working checkout page you can load on your domain
A configured Browser Key restricted to your domain
A cart flow that can add items, collect customer details, and place an order
A thank-you page that loads after successful checkout

Troubleshooting

Hosted Fields don’t load (blank card inputs)

Common causes:

You are not using HTTPS in production
The Browser Key does not allow your domain as a referrer
You are testing on a different port/domain than what’s whitelisted

Fix:

Confirm your current URL exactly matches your allowed referrers.
Generate a new Browser Key with correct https://… referrers.
Update checkout.js with the new key.

[Image Placeholder: “Browser console showing Hosted Fields error”]

CORS errors in the browser console

Symptoms:

Console shows blocked requests (Origin not allowed)
Cart calls fail

Fix:

Ensure the referrer list in setup-browser-key.php includes the exact origin you’re using:
- http://localhost:3000 (local)
- https://yourdomain.com (production)

[Image Placeholder: “CORS error example”]

Items won’t add to cart

Check:

The Item ID exists and is active
You’re using the correct parameter format: ?ADD=ITEM_ID

Try:

A different known-good item
Confirm the cart renders at all (even empty)

Merchant ID or storefront domain is wrong

Symptoms:

Authentication or lookup failures
Cart or checkout returns errors

Fix:

Re-check:
- Merchant ID in UltraCart (Configuration → Account)
- Storefront domain (Configuration → Storefront)

Frequently Asked Questions

Question: Why are my REST API requests blocked when using Claude Code or another AI coding tool?

Answer: UltraCart may block REST API requests when the application sends a generic Python user agent, such as the default user agent generated by some scripts, libraries, or AI coding tools. UltraCart’s firewall does not allow requests that appear to come from generic Python scripts because they can resemble automated scraping or abusive traffic.

To avoid this issue, configure your REST API application to send a more descriptive application user agent. For example:

OpenAPI-Generator/4.1.91/python

When using tools such as Claude Code, review the generated HTTP client code and confirm that the User-Agent header is set explicitly. The user agent should identify the application or SDK rather than relying on a default Python value.

Example header:

User-Agent: OpenAPI-Generator/4.1.91/python

Tip: If your API requests suddenly receive firewall-related errors or appear to be blocked before reaching the UltraCart REST API, check the User-Agent header first. A generic Python user agent is a common cause when the client code was generated or modified by an AI coding tool.

Next Steps

Brand the checkout: update css/checkout.css
Customize fields and validation: update index.html and the form mapping in js/checkout.js
Add analytics and tracking (carefully) without modifying compiled StoreFront theme files
Re-evaluate whether Visual Builder can meet your needs with less long-term maintenance overhead

https://www.ultracart.com/api/#introduction.html

UltraCart HTTP 403 Error Troubleshooting Guide

REST API Errors

Was this page helpful?

Overview​

Consider Visual Builder First (Recommended for Most Merchants)​

What You’ll Need​

Accounts & access​

From UltraCart​

On your computer​

Software (one-time installs)​

Steps​

1) Download and unzip the starter package​

2) Create your Simple Key in UltraCart​

3) Install PHP (if needed)​

Windows (common case)​

Mac​

4) Install Composer​

Windows​

Mac​

5) Generate a Browser Key (localhost testing)​

6) Configure your checkout (js/checkout.js)​

7) Run the checkout locally​

Windows (simple local server using PHP)​

Mac (simple local server using Python)​

8) Add an item to the cart​

9) Test placing an order​

10) Go live on your real domain (production)​

A) Update allowed referrers for production​

B) Update js/checkout.js​

C) Upload files to your hosting​

D) Confirm HTTPS​

Expected Outcome​

Troubleshooting​

Hosted Fields don’t load (blank card inputs)​

CORS errors in the browser console​

Items won’t add to cart​

Merchant ID or storefront domain is wrong​

Frequently Asked Questions​

Next Steps​

Related Documentation​

Overview

Consider Visual Builder First (Recommended for Most Merchants)

What You’ll Need

Accounts & access

From UltraCart

On your computer

Software (one-time installs)

Steps

1) Download and unzip the starter package

2) Create your Simple Key in UltraCart

3) Install PHP (if needed)

Windows (common case)

Mac

4) Install Composer

Windows

Mac

5) Generate a Browser Key (localhost testing)

6) Configure your checkout (`js/checkout.js`)

7) Run the checkout locally

Windows (simple local server using PHP)

Mac (simple local server using Python)

8) Add an item to the cart

9) Test placing an order

10) Go live on your real domain (production)

A) Update allowed referrers for production

B) Update `js/checkout.js`

C) Upload files to your hosting

D) Confirm HTTPS

Expected Outcome

Troubleshooting

Hosted Fields don’t load (blank card inputs)

CORS errors in the browser console

Items won’t add to cart

Merchant ID or storefront domain is wrong

Frequently Asked Questions

Next Steps

Related Documentation