# ShipThis Developer Portal — full documentation

> The REST API base URL is https://api.shipthis.co/api/v3 and authenticates via an `x-api-key` header.

## Introduction

Start here to understand how the Shipthis developer surface is organized.

Shipthis exposes four integration surfaces: a REST API, JavaScript and Python SDKs, embeddable web components, and an in-app builder for custom automations. These docs are grouped by surface so you can go directly to what you are building.

**What you can build**
- _API_ **Direct REST access**: Authenticate with an API key and call shipment, invoice, customer, and clearance endpoints from any HTTP client.
- _SDKs_ **Higher-level integration**: Use the JavaScript or Python SDK for typed helpers, auth management, and structured access to Shipthis resources.
- _Web Components_ **Embeddable UI**: Drop the quotation widget into any website with two lines of HTML. Fully themeable, no framework required.
- _Builder_ **Custom automations**: Build outbound event automations and inbound webhook handlers that run inside your Shipthis environment.

**Recommended starting path**
- Create an API key and set it in your environment variables.
- Make one successful GET request from the API Reference or curl.
- Switch to an SDK if you want typed helpers and less boilerplate.
- Use web components if you need embeddable UI rather than raw API calls.
- Use the Builder for event-driven automations inside Shipthis.
- Review Error Codes before going to production.

**Quick links**
- [API Reference](/api-reference): Interactive endpoint tester — authorize once and run requests directly.
- [JavaScript SDK](/resources/sdks/javascript): Installation, auth, and examples for browser and Node.js.
- [Python SDK](/resources/sdks/python): Installation and examples for server-side Python integrations.
- [Quotation Widget](/resources/components/quotation-widget): Embed a fully themeable quote form into any website.

## APIs

Everything needed to authenticate, send, and test your first requests.

### Getting Started

Set up the minimum pieces required before you make your first API call.

Shipthis APIs are exposed from a single base URL and authenticated with your API key. For most teams the fastest path is: create key, open API Reference, send one GET request, then wire the same request into your app.

**Minimum setup**
- _Base URL_ **https://api.shipthis.co/api/v3**: Use the v3 API base for direct REST requests and for validating endpoint paths in examples.
- _Headers_ **x-api-key**: Authenticate requests with the x-api-key header. Some flows may also support Authorization: Bearer.
- _Best first test_ **Read request**: Start with a safe GET request so you can confirm auth and payload shape before creating or updating data.

**Suggested first-run sequence**
1. **Create an API key** — Generate a key for the environment you are working in and keep it out of source control.
2. **Use the interactive reference** — Open API Reference, authorize with your key, and test a simple endpoint to confirm access.
3. **Move the same call into code** — Reuse the exact path, method, and headers in curl, JavaScript, Python, or your preferred client.

### API Keys

Create, store, and rotate credentials safely.

Use separate keys for development and production. Treat every key like a password and keep it in your environment configuration, never in the frontend bundle or repository.

**Create and manage a key**
1. **Open Shipthis settings** — Go to the API Keys area in your account or workspace settings.
2. **Create a scoped key** — Name the key clearly so its environment and purpose are obvious when you rotate or revoke it later.
3. **Store it in env vars** — Keep the key in deployment secrets or local environment files that are excluded from version control.

**Key hygiene**
- Use separate keys for local, staging, and production environments.
- Rotate keys on a fixed schedule or immediately after exposure.
- Limit who can see raw production credentials.
- Revoke and replace keys that are no longer used.

**Example environment variable**
```bash
export SHIPTHIS_API_KEY="YOUR_API_KEY"
```

### Authentication

Use consistent headers so requests authenticate cleanly across tools.

Most integrations should send the x-api-key header on every request. Keep auth injection centralized in your HTTP client so you do not duplicate it across endpoints.

**Header example**
```bash
curl -X GET https://api.shipthis.co/api/v3/shipments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"
```

> **Use one auth strategy per client**: If your app wraps Shipthis calls internally, add the key at the HTTP client layer rather than repeating headers in every function.

**Common auth issues**
- Missing x-api-key header
- Wrong environment key
- Expired or revoked credentials
- Calling the correct path with the wrong user context

### First API

Make one successful request before you design the rest of your flow.

Your first request should prove four things: the base URL is correct, the key is valid, the response shape is understood, and your application can parse the returned JSON.

**First request with curl**
```bash
curl -X GET https://api.shipthis.co/api/v3/shipments \
  -H "x-api-key: YOUR_API_KEY"
```

**First request with fetch**
```javascript
const response = await fetch('https://api.shipthis.co/api/v3/shipments', {
  headers: {
    'x-api-key': SHIPTHIS_API_KEY ?? '',
    Accept: 'application/json',
  },
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);
```

**Verify after the call**
- Response status matches expectation.
- Returned data shape is what your code expects.
- You know which IDs or fields will be needed by the next call.

### Test First API

Use the interactive reference to validate your requests before wiring them into production code.

The fastest way to eliminate guesswork is to test the request in the API Reference first. Once it succeeds there, copy the method, path, and request structure into your app.

**Suggested test flow**
1. **Open API Reference** — Go to the interactive API Reference and choose the relevant user type if needed.
2. **Authorize with your key** — Paste your API key once so you can test multiple endpoints in the same session.
3. **Run a safe GET endpoint** — Confirm the endpoint returns 200 and inspect the exact response payload.
4. **Promote the request into code** — Reuse the same request data in curl, fetch, axios, or one of the Shipthis SDKs.

- [Open API Reference](/api-reference): Interactive tester for endpoints and auth validation.

## SDK & Resources

Use the official SDKs and web components when you want faster integration patterns.

### JavaScript SDK

Use the JavaScript SDK in browser or Node.js applications.

Lightweight JavaScript wrapper for the Shipthis API. Works in Node.js ≥18 and the browser. Ships TypeScript types.

- _Install_ **npm i shipthisapi-js**: Add the package to your application and initialize it with your organization and auth data.

**Highlights**
- Browser + Node.js ≥18 support
- TypeScript types included
- xApiKey and password-based auth
- Air, Sea & Land freight operations
- Customer & party management

**Quick example**
```javascript
import { ShipthisAPI } from 'shipthisapi-js';

const shipthisApi = new ShipthisAPI({
  userType: 'employee',
  organisationId: 'your_org_id',
  xApiKey: SHIPTHIS_API_KEY,
  locationId: 'your_location_id',
  regionId: 'your_region_id',
});

await shipthisApi.connect();

// Fetch required reference data
const customers = await shipthisApi.Shipment.getCustomers();
const terms     = await shipthisApi.Shipment.getShipmentTerms();
const opExec    = await shipthisApi.Shipment.getOperationExecutive();

// Create a sea freight shipment
const shipment = await shipthisApi.Shipment.createSeaFreight({
  job_id: '',
  shipment_name: 'My first shipment',
  shipment_class: 'house',
  customer_name: customers.items[0],
  shipment_type: 'import',
  shipment_term: terms.items[0],
  operation_executive: opExec.items[0],
});

console.log('Shipment created:', shipment);
```

- [Full JavaScript SDK docs](/resources/sdks/javascript): Read full installation notes, examples, and feature details.

### Python SDK

Use the Python SDK for server-side integrations and backend automation.

Generic Python wrapper for the Shipthis API. Operates on collections by name — every resource in the platform accessible through a single consistent interface.

- _Install_ **pip install shipthisapi-python**: Initialize the client with your organization, API key, region, and location settings.

**Highlights**
- Generic collection-based API
- Async-ready via httpx
- Workflow & status transitions
- Bulk operations & file upload
- Reporting with date range filters

**Quick example**
```python
from ShipthisAPI.shipthisapi import ShipthisAPI

shipthisapi = ShipthisAPI(
    organisation='your_org_id',
    x_api_key='your_api_key',
    region_id='your_region_id',
    location_id='your_location_id',
    user_type='employee',
)

shipthisapi.connect()

# Fetch required reference data
customers = shipthisapi.get_list('customer')
terms     = shipthisapi.get_list('shipment_term')

# Create a sea freight shipment
shipment = shipthisapi.create_item('sea_shipment', data={
    'shipment_name': 'My first shipment',
    'shipment_class': 'house',
    'shipment_type': 'import',
    'customer_name': customers[0],
    'shipment_term': terms[0],
})

print('Created:', shipment)
```

- [Full Python SDK docs](/resources/sdks/python): Read full examples and integration notes for Python projects.

### Web Components

Embed ready-made Shipthis UI into websites and portals.

The Shipthis Quotation Form Wrapper is a prebuilt web component you can embed in your website. It connects to your Shipthis ERP account and lets prospects generate accurate quotes in real time.

**Where this works well**
- Quote request forms

**Highlights**
- Framework agnostic
- Fully customizable
- Multiple layout options
- Theme support
- Responsive design

**Embed example**
```html
<shipthis-quotation
  organisation-id="YOUR_ORG_ID"
  api-key="YOUR_API_KEY"
  captcha-key="YOUR_CAPTCHA_KEY"
  title="Request a Quote"
  layout="accordion"
  show-header="true"
  show-footer="true"
  show-clear-button="true"
></shipthis-quotation>

<!-- Add before </body> -->
<script type="module"
  src="https://cdn.jsdelivr.net/gh/shipthisco/quotation-web-component@master/dist/qwc.js">
</script>
```

- [View resources](/resources/components): Browse web component documentation and implementation details.

## Builder

Guides for creating custom apps and workflow automations in Shipthis.

### Overview

Understand the builder model before creating your first app.

The builder is for custom apps that run inside your Shipthis environment. A typical app has one or more code blocks, each configured for an outgoing workflow or an inbound webhook.

- _Apps_ **Container for your integration**: Each app groups related code blocks, metadata, and execution behavior.
- _Code blocks_ **Where logic runs**: Each block contains JavaScript or Python and is triggered by an event or webhook.
- _Flow types_ **Outgoing or webhook**: Outgoing blocks react to Shipthis events. Webhook blocks receive external payloads into Shipthis.

- [Open Builder](/builder): Go to the builder dashboard and create or edit apps.

### Create App

Create an app shell before you configure blocks and code.

**Create a new app**
1. **Open the builder dashboard** — Start from the Apps screen where all custom integrations are listed.
2. **Click New app** — Create a named app with a clear description so other developers know its purpose.
3. **Add the first code block** — Choose the language and trigger model that matches the workflow you want to automate.

> **Keep apps scoped**: Prefer smaller apps with clear ownership over one large app that mixes unrelated workflows.

### Configure Blocks

Choose the right flow type and event model for each code block.

Choose outgoing when Shipthis should trigger your code from an internal event. Choose webhook when an external system needs to send data into your app endpoint.

**Block choices**
| Mode | When to use it | What to configure |
| --- | --- | --- |
| Outgoing | React to Shipthis-side events and modules | Select the view, trigger timing, and block code |
| Webhook | Receive inbound payloads from external systems | Choose JSON or XML payload type and process the incoming data |

**Before saving a block**
- Name the block for the exact action it performs.
- Verify whether the flow is outgoing or webhook.
- Check the payload format and required fields.
- Keep credentials and secrets out of inline code.

### Run Tests

Validate block behavior before you rely on it in live workflows.

**Test loop**
1. **Open the block test modal** — Use the built-in test flow to provide a document or sample payload depending on the block type.
2. **Run with realistic data** — Use actual payload structure so your logic is validated against production-like inputs.
3. **Inspect logs and results** — Confirm the block output and error handling before moving on to the next block or app release.

> **Test webhook blocks with representative payloads**: If your block expects JSON or XML from an external system, validate with real sample payloads so field-path assumptions do not break later.

## Error Codes

Use status codes and error payloads to design retries, alerts, and fallback behavior.

Treat HTTP status codes as part of your integration contract. Your application should log enough context to tell whether the problem is with auth, validation, rate limits, or the upstream service.

**Common responses**
| Code | Meaning | Suggested action |
| --- | --- | --- |
| 200 | Request succeeded | Parse the response and continue the workflow. |
| 201 | Resource created | Store returned IDs for later operations. |
| 400 | Invalid request | Review payload shape and required fields. |
| 401 | Authentication failed | Check API key presence, value, and environment. |
| 403 | Forbidden | Verify permissions or account-level access. |
| 404 | Resource not found | Check the endpoint path and referenced IDs. |
| 429 | Rate limited | Retry with backoff and reduce request bursts. |
| 500 | Server error | Retry safely if the endpoint is idempotent and log the failure. |
| 503 | Service unavailable | Retry later and surface the outage in monitoring. |

**Example error payload handling**
```javascript
const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json().catch(() => ({}));

  console.error('Shipthis API error', {
    status: response.status,
    error,
  });

  if (response.status === 429) {
    // add retry or backoff logic here
  }
}
```

**Production expectations**
- Log response status and a safe subset of the error payload.
- Retry only when the failure mode is safe to retry.
- Alert on repeated 401, 403, 429, and 5xx responses.
- Keep validation errors visible to the team that owns the integration.