Skip to main content
How-to

C# SDK

Install the C# SDK from NuGet, 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.
  • .NET 4.0 or later.

Install​

Install-Package RestSharp -Version 105.1.0
Install-Package Newtonsoft.Json
Install-Package JsonSubTypes
Install-Package com.ultracart.admin.v2 -Version 4.1.129

Check NuGet for the current release before pinning a different version.

warning

Pin RestSharp at 105.1.0. Later versions carry a bug that breaks file uploads (RestSharp#742), which affects any operation that sends a file, including chargeback evidence and item digital delivery.

The SDK also needs Json.NET 7.0.0 or later and JsonSubTypes 1.2.0 or later. The DLLs bundled in the package are not always current, so installing all four from NuGet is more reliable than referencing the bundled copies.

Authenticate​

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

using com.ultracart.admin.v2.Api;

OrderApi orderApi = new OrderApi(Environment.GetEnvironmentVariable("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, which does not belong in your code.

Retrieve an order​

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

// Trimmed from sdk_samples/csharp/order/GetOrder.cs
using System;
using com.ultracart.admin.v2.Model;
using Newtonsoft.Json;

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.Error != null)
{
    Console.Error.WriteLine(apiResponse.Error.DeveloperMessage);
    Console.Error.WriteLine(apiResponse.Error.UserMessage);
    Environment.Exit(1);
}

Order order = apiResponse.Order;
Console.WriteLine(JsonConvert.SerializeObject(
    order, new JsonSerializerSettings { Formatting = Formatting.Indented }));

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.

Method names are PascalCase in this SDK (GetOrder, not getOrder), while the model properties keep the API's own casing. 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 csharp/ in the samples repository.
  • Error reference for the specific failures you are likely to hit, and how to handle each one.
Was this page helpful?