Skip to main content
How-to

TypeScript SDK

Install the TypeScript SDK, configure a client, and retrieve an order with typed models.

Before you start​

  • A Simple Key. Generate one under Configuration → Back Office → Authorized Applications. See Creating a Simple Key. For an application that multiple merchants connect to their own accounts, use OAuth 2.0 instead.
  • Node.js. The client returns promises and uses the platform fetch.

This is a separate package from the JavaScript SDK, not a set of type definitions layered over it. The two have different client setup and different method signatures, so pick one.

Install​

npm install ultracart_rest_api_v2_typescript --save

Authenticate​

Each API class takes a Configuration. Pass both the key and apiVersion:

import { Configuration, OrderApi } from 'ultracart_rest_api_v2_typescript';

const orderApi = new OrderApi(new Configuration({
    apiKey: process.env.UC_API_KEY!,   // <- your merchant Simple Key
    apiVersion: '2017-03-01',
}));

apiVersion populates the X-UltraCart-Api-Version header on every request. Omitting it sends the header empty and the request fails, so treat it as required rather than optional. See Versioning for what the value controls.

warning

Keep the key out of source control and out of anything that ships to a browser. A Simple Key carries the permissions of the application it belongs to.

Retrieve an order​

This is the GetOrder sample from sdk_samples, trimmed to the call itself:

// Trimmed from sdk_samples/typescript/order/GetOrder.ts
import { OrderResponse } from 'ultracart_rest_api_v2_typescript';

const expansion = 'item,summary,billing,shipping,shipping.tracking_number_details';
const orderId = 'DEMO-0009104390';                // <- an order ID in your account

const apiResponse: OrderResponse = await orderApi.getOrder({ orderId, expand: expansion });

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));

Methods take a single object argument rather than positional parameters, which is the clearest difference from the JavaScript SDK. The expand value controls how much of the order comes back; Expanding objects lists the valid values.

A returned order is typed as optional, so narrow it before use. UltraCart application errors arrive on apiResponse.error rather than as a thrown exception.

Next​

  • Essentials for pagination, expansion, errors, and rate limits.
  • API Samples to browse a sample for every operation, or go straight to typescript/ in the samples repository.
  • API Reference for every operation, with a TypeScript tab on each page.
Was this page helpful?