Java SDK

Add the Java SDK to your build, authenticate, and retrieve an order.

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.
• Java 1.8 or newer, with Maven 3.8.3 or newer, or Gradle 7.2 or newer.

Install

Maven:

<dependency>
    <groupId>com.ultracart</groupId>
    <artifactId>rest-sdk</artifactId>
    <version>4.1.129</version>
</dependency>

Gradle:

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.ultracart:rest-sdk:4.1.129"
}

Check Maven Central for the current release before pinning a different version.

Authenticate

Every API class has a constructor that takes a Simple Key and builds a configured client:

import com.ultracart.admin.v2.OrderApi;

OrderApi orderApi = new OrderApi(System.getenv("UC_API_KEY"));   // <- your merchant Simple Key

That constructor sets the X-UltraCart-Api-Version header along with the credential, so no further client setup is needed.

warning

Read the key from the environment or a secret store rather than hardcoding it. The samples repository hardcodes a shared development key and disables TLS verification; neither belongs in your code.

Retrieve an order

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

// Trimmed from sdk_samples/java/src/order/GetOrder.java
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.ultracart.admin.v2.models.*;
import com.ultracart.admin.v2.util.ApiException;

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

OrderResponse apiResponse = orderApi.getOrder(orderId, expansion);

if (apiResponse.getError() != null) {
    System.err.println(apiResponse.getError().getDeveloperMessage());
    System.err.println(apiResponse.getError().getUserMessage());
    System.exit(1);
}

Order order = apiResponse.getOrder();
Gson gson = new GsonBuilder().setPrettyPrinting().create();
System.out.println(gson.toJson(order));

The expansion string 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.

Failures reach you two ways. Transport and HTTP failures throw ApiException, while UltraCart application errors come back on the response through getError(). Handle both.

Next

• Essentials for pagination, expansion, errors, and rate limits.
• API Samples to browse a sample for every operation, or go straight to java/src/ in the samples repository. Java is a Maven project there, so its samples sit under java/src/ rather than java/.
• Error reference for the specific failures you are likely to hit, and how to handle ApiException.