Python SDK

v3.1.2

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

GitHub (opens in new tab)MITMaintained

Installation

$ pip install shipthisapi-python

Quick start

Initialize the client with your organisation ID and API key. Use your organisationId during development.

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)

Resources & methods

ResourceMethods
.sea_shipmentcreate · retrieve · update · list
.air_shipmentcreate · retrieve · accept · list
.invoicecreate · retrieve · update · list
.customerscreate · retrieve · update · list
.clearance_jobcreate · retrieve · update · list
ℹ

The methods shown here are a sample of what the SDK covers. Shipthis exposes a generic collection API that gives access to every resource in the platform. See the full API reference ↗

Authentication

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',  # 'employee' | 'customer', default: 'employee'
)

shipthisapi.connect()

Collection operations

The Python SDK is collection-based — every resource is accessed by passing its collection name as a string.

Fetch a list

python
# Get sea shipments (paginated)
shipments = shipthisapi.get_list('sea_shipment', page=1, count=20)

# With filters
invoices = shipthisapi.get_list(
    'invoice',
    filters={'status': 'pending'},
    sort=[{'field': 'created_at', 'order': 'desc'}]
)

Fetch a single item

python
shipment = shipthisapi.get_one_item('sea_shipment', doc_id='<document_id>')

Search

python
results = shipthisapi.search('sea_shipment', query='Demo shipment')

Create

python
new_shipment = shipthisapi.create_item('sea_shipment', data={
    'shipment_name': 'My sea shipment',
    'shipment_class': 'house',
    'shipment_type': 'import',
})

Update

python
# Full replace
shipthisapi.update_item('sea_shipment', object_id='<id>', updated_data={...})

# Partial patch
shipthisapi.patch_item('sea_shipment', object_id='<id>', update_fields={'status': 'active'})

Delete

python
shipthisapi.delete_item('sea_shipment', object_id='<id>')

Workflow operations

python
# Get current status
status = shipthisapi.get_job_status('sea_shipment', object_id='<id>')

# Trigger a workflow action
shipthisapi.set_job_status('sea_shipment', object_id='<id>', action_index=1)

# Primary status transition
shipthisapi.primary_workflow_action(
    collection='sea_shipment',
    workflow_id='<workflow_id>',
    object_id='<id>',
    action_index=0,
    intended_state_id='<state_id>'
)

Reporting

python
report = shipthisapi.get_report_view(
    report_name='invoice_manage',
    start_date_iso='2025-01-01',
    end_date_iso='2025-12-31',
    filters={'location': 'new_york'}
)

Utilities

python
# Organisation info
info = shipthisapi.info()

# Bulk edit
shipthisapi.bulk_edit('sea_shipment', ids=['<id1>', '<id2>'], update_data={'flag': True})

# File upload
file_meta = shipthisapi.upload_file('/path/to/file.pdf')

# Exchange rate
rate = shipthisapi.get_exchange_rate('EUR', target_currency='USD')

# Autocomplete reference field
suggestions = shipthisapi.autocomplete('port', data={'query': 'New York'})
All SDKsResources