Quickstart

Three steps from nothing to a working integration: create an API key, call the REST API with it, and pull back exactly the data you need.

Every request in this guide goes to https://secure.ultracart.com/rest/v2.

Prerequisites

• An UltraCart account with access to Configuration → Back Office → Authorized Applications.
• curl, or any HTTP client you prefer.

warning

UltraCart has no sandbox environment. An API key acts on the account that issued it, and a test order is a real order in that account. To keep experiments away from live data, sign up for a second UltraCart account and use it as your developer account.

Step 1: Create an API key

Simple key authentication fits in-house code that talks to a single account. If you are building an application that multiple merchants will install, use OAuth 2.0 instead of the steps below.

1. Go to Configuration → Back Office → Authorized Applications.
2. Create an application and choose simple key as the authentication scheme.
3. Copy the generated key.

API Simple Key covers the screen in detail. The key carries the permissions of the account that issued it, so store it the way you would store a password. If your code runs from a fixed IP address, restrict the key to it.

Step 2: Make your first request

Retrieve a single item to confirm the key works:

curl -X GET "https://secure.ultracart.com/rest/v2/item/items?_limit=1" \
  -H "Accept: application/json" \
  -H "X-UltraCart-Api-Version: 2017-03-01" \
  -H "x-ultracart-simple-key: YOUR_API_KEY"   # <- the key from step 1

A successful call returns 200 OK and an items array:

{
  "items": [
    {
      "merchant_item_oid": 6532718,
      "merchant_id": "DEMO",
      "merchant_item_id": "1",
      "description": "Example single bottle item"
    }
  ]
}

Two details matter from here on:

• The version header is required. Requests without X-UltraCart-Api-Version fail. It is the most common reason a first call returns an error. See Versioning.
• Every response carries X-UltraCart-Request-Id. Record it. Support can trace a request by that value.

Step 3: Expand a single item

Step 2 returned a list. To work with one record, request it by its merchant_item_oid and use _expand to pull in the related data you want in the same call:

curl -X GET "https://secure.ultracart.com/rest/v2/item/items/YOUR_ITEM_OID?_expand=pricing,shipping" \
  -H "Accept: application/json" \
  -H "X-UltraCart-Api-Version: 2017-03-01" \
  -H "x-ultracart-simple-key: YOUR_API_KEY"

Substitute YOUR_ITEM_OID with a merchant_item_oid from the step 2 response.

Without _expand, an item comes back in its basic form:

{
  "merchant_item_oid": 875851,
  "merchant_id": "DEMO",
  "merchant_item_id": "Baseball Bat",
  "description": "Wood Baseball Bat",
  "last_modified_dts": "2016-08-11T16:14:46-04:00",
  "creation_dts": "2009-01-14T18:30:42-05:00"
}

Each name you add to _expand attaches another branch of the object. Expansion nests, so shipping.distribution_centers reaches inventory data one level down. Ask for what you need and nothing else: every expansion costs response size and server time. Expanding Objects covers the full syntax, including thumbnail filters.

Troubleshooting

Symptom	Cause
Request fails with no useful body	The X-UltraCart-Api-Version header is missing.
401 or 403	The key is wrong, revoked, or restricted to a different IP address.
Request fails over plain HTTP	All API traffic must use HTTPS.
404 on a single item	The merchant_item_oid belongs to a different account, or the item was deleted.

Next steps

• Essentials covers authentication, pagination, rate limits, error handling, and webhooks.
• API reference documents every endpoint, with runnable samples in eight languages.
• SDKs wrap the REST API for your language and set the version header for you.
• Before you place orders against a live account, read Test Payments in UltraCart. A test order is a real order placed with a registered test card, not an isolated one.