Skip to main content
How-to

JavaScript SDK

Install the Node.js SDK, authenticate, and retrieve an order.

Before you start​

  • A Simple Key. Generate one under Configuration → Back Office → Authorized Applications. See Creating a Simple Key. If you are building an application that multiple merchants will connect to their own accounts, use OAuth 2.0 instead.
  • Node.js. The package is published for Node and also runs in a browser bundle. Writing TypeScript? Use the TypeScript SDK, which is a separate package with typed models and a promise-based client.

Install​

npm install ultra_cart_rest_api_v2 --save

Authenticate​

ApiClient carries the credential and the API version header. Its usingApiKey() method sets both, then each API class takes the configured client:

import { ApiClient, OrderApi } from 'ultra_cart_rest_api_v2';

const apiClient = new ApiClient();
apiClient.usingApiKey(process.env.UC_API_KEY);   // <- your merchant Simple Key

const orderApi = new OrderApi(apiClient);

usingApiKey() sets X-UltraCart-Api-Version to 2017-03-01 alongside the key. Building the client by hand without that header produces a failed request, so prefer this method over assigning authentications.ultraCartSimpleApiKey.apiKey yourself.

warning

Keep the key out of source control and out of browser bundles. A Simple Key carries the permissions of the application it belongs to. For client-side code, use a browser key instead.

Retrieve an order​

The JavaScript client is callback-based. This is the getOrder sample from sdk_samples, trimmed to the call itself and wrapped in a promise:

// Trimmed from sdk_samples/javascript/order/getOrder.js

// Expansion controls how much of the order is returned. The full object is
// large, so request only the branches you need.
const expansion = 'item,summary,billing,shipping,shipping.tracking_number_details';
const orderId = 'DEMO-0009104390';                // <- an order ID in your account

const apiResponse = await new Promise((resolve, reject) => {
    orderApi.getOrder(orderId, { _expand: expansion }, (error, data) => {
        error ? reject(error) : resolve(data);
    });
});

if (apiResponse.error) {
    console.error('Developer Message:', apiResponse.error.developer_message);
    console.error('User Message:', apiResponse.error.user_message);
    throw new Error('Failed to retrieve order');
}

console.log(JSON.stringify(apiResponse.order, null, 2));

The _expand value controls how much of the order comes back. Order objects are large, and requesting every branch across thousands of orders is the most common cause of slow SDK code. Expanding objects lists the valid values.

Errors arrive two ways. Transport and HTTP failures reach the callback's error argument, while UltraCart application errors come back on apiResponse.error with a developer_message and a user_message. Handle both.

Running in a browser​

The package works in the browser through browserify. With main.js as your entry file:

npm install -g browserify
browserify main.js > bundle.js

Webpack builds can fail with "Module not found: Error: Cannot resolve module" because of the AMD loader. Disable it:

module: {
  rules: [
    {
      parser: {
        amd: false
      }
    }
  ]
}

Next​

Was this page helpful?