> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Backend SDKs

Call the Solvimon API from your server in TypeScript, Python or Java with typed clients for every endpoint, instead of building HTTP requests by hand.

---

## Why use a backend SDK

The backend SDKs wrap the same REST API that the [API reference](/api-docs) describes. Each SDK gives you typed request and response models, so your editor catches a missing field or a wrong enum value before the request is sent. Use them from your own servers only: they authenticate with your secret API key, which must never reach a browser. To render billing UI in the browser, use the [Frontend Components](/sdk/frontend-components/overview) instead.

## Available SDKs

| Language   | Package                                                                                                                  | Requirements                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| TypeScript | [`@solvimon/solvimon-typescript-sdk`](https://www.npmjs.com/package/@solvimon/solvimon-typescript-sdk) (npm)             | Node.js 18 or later, or any runtime with the Fetch API |
| Python     | [`solvimon-python-sdk`](https://pypi.org/project/solvimon-python-sdk/) (PyPI)                                            | Python 3.10 or later                                   |
| Java       | [`com.solvimon:solvimon-java-sdk`](https://central.sonatype.com/artifact/com.solvimon/solvimon-java-sdk) (Maven Central) | Java 8 or later                                        |

All three SDKs are generated from the Solvimon OpenAPI specification, so every endpoint in the API reference is available in each language.

## Install

**`TypeScript`**

```bash TypeScript
npm install @solvimon/solvimon-typescript-sdk
```

**`Python`**

```bash Python
pip install --pre solvimon-python-sdk
```

**`Java (Maven)`**

```xml Java (Maven)
<dependency>
  <groupId>com.solvimon</groupId>
  <artifactId>solvimon-java-sdk</artifactId>
  <version>0.0.4-beta</version>
</dependency>
```

**`Java (Gradle)`**

```groovy Java (Gradle)
implementation "com.solvimon:solvimon-java-sdk:0.0.4-beta"
```

The current Python package version is a pre-release on PyPI, which is why the command needs `--pre`.

## Configure the client

Each SDK needs two things: the base URL of the environment and an API key. Create a key in Desk as described in [API key creation](/platform-guides/platform-configuration/api-key-creation), and keep it in an environment variable rather than in your code.

| Environment | Base URL                        |
| ----------- | ------------------------------- |
| Sandbox     | `https://test.api.solvimon.com` |
| Live        | `https://api.solvimon.com`      |

The SDKs default to the sandbox. Set the base URL explicitly so that switching to live is a configuration change, not a code change.

**`TypeScript`**

```ts TypeScript
import { Configuration, CustomersApi } from '@solvimon/solvimon-typescript-sdk';

const config = new Configuration({
  basePath: 'https://test.api.solvimon.com',
  apiKey: process.env.SOLVIMON_API_KEY,
});

const customers = new CustomersApi(config);
```

**`Python`**

```python Python
import os
import solvimon_python_sdk

configuration = solvimon_python_sdk.Configuration(
    host="https://test.api.solvimon.com",
    api_key={"API-Key": os.environ["SOLVIMON_API_KEY"]},
)

api_client = solvimon_python_sdk.ApiClient(configuration)
customers = solvimon_python_sdk.CustomersApi(api_client)
```

**`Java`**

```java Java
import com.solvimon.sdk.ApiClient;
import com.solvimon.sdk.Configuration;
import com.solvimon.sdk.api.CustomersApi;

ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://test.api.solvimon.com");
client.setApiKey(System.getenv("SOLVIMON_API_KEY"));

CustomersApi customers = new CustomersApi(client);
```

The SDKs send the key in the `X-API-KEY` header, the same header the API reference uses. In Python, the key in the `api_key` dictionary must be `"API-Key"`.

## Make your first call

This example creates an organization customer, the same request as [POST /v1/customers](https://docs.solvimon.com/api-docs/configuration-api/customers/post-customers).

**`TypeScript`**

```ts TypeScript
import { ResponseError } from '@solvimon/solvimon-typescript-sdk';

try {
  const customer = await customers.postCustomers({
    version: '1',
    customerCreateRequest: {
      type: 'ORGANIZATION',
      reference: 'acme-corp',
      email: 'billing@acme.example',
      organization: { legal_name: 'Acme Corp B.V.' },
    },
  });
  console.log(customer.id);
} catch (err) {
  if (err instanceof ResponseError) {
    console.error(err.response.status, await err.response.json());
  } else {
    throw err;
  }
}
```

**`Python`**

```python Python
from solvimon_python_sdk.models import CustomerCreateRequest, OrganizationCreateRequest
from solvimon_python_sdk.rest import ApiException

request = CustomerCreateRequest(
    type="ORGANIZATION",
    reference="acme-corp",
    email="billing@acme.example",
    organization=OrganizationCreateRequest(legal_name="Acme Corp B.V."),
)

try:
    customer = customers.post_customers(version="1", customer_create_request=request)
    print(customer.id)
except ApiException as e:
    print(e.status, e.body)
```

**`Java`**

```java Java
import com.solvimon.sdk.ApiException;
import com.solvimon.sdk.model.Customer;
import com.solvimon.sdk.model.CustomerCreateRequest;
import com.solvimon.sdk.model.OrganizationCreateRequest;

CustomerCreateRequest request = new CustomerCreateRequest()
    .type(CustomerCreateRequest.TypeEnum.ORGANIZATION)
    .reference("acme-corp")
    .email("billing@acme.example")
    .organization(new OrganizationCreateRequest().legalName("Acme Corp B.V."));

try {
  Customer customer = customers.postCustomers("1", null, request);
  System.out.println(customer.getId());
} catch (ApiException e) {
  System.err.println(e.getCode() + " " + e.getResponseBody());
}
```

## How the SDKs map to the API

Once you know the endpoint in the API reference, you can find the SDK call:

* **API classes follow the resource.** Customer endpoints are on `CustomersApi`, invoice endpoints on `InvoicesApi`, event ingestion on `IngestApi`, and so on.
* **Method names follow the HTTP method and path.** `POST /v1/customers` is `postCustomers` (`post_customers` in Python), and `GET /v1/customers/{id}` is `getCustomersByResourceIdOrReference`.
* **`version` is a required argument on every call.** Pass `"1"`.
* **Request and response fields keep the API's snake_case names** in TypeScript and Python, so field names match the API reference. Java uses camelCase setters and getters, such as `legalName()` for `legal_name`.
* **Optional headers are arguments.** To act on a specific platform, pass `xPlatformId` (TypeScript and Java) or `x_platform_id` (Python).

## Errors

A response with a 4xx or 5xx status raises an error that carries the status code and the response body, as shown in the example above: `ResponseError` in TypeScript, `ApiException` in Python and Java. The body has the same structure as any API error; see [Errors](/platform-guides/for-developers/errors) for the reasons Solvimon returns.

## Edge cases

* The SDKs do not retry failed requests. To retry a `POST` safely, send an [idempotency key](/platform-guides/for-developers/idempotency).
* SDK versions are published separately from API releases, so a field that was just added to the API may not be in the SDK version you have installed yet. The [API reference](/api-docs) is the source of truth for every field; upgrade the SDK to pick up new ones.