Shipping

Shipengine

Learn how to use Shipengine with Composio

Overview

SLUG: SHIPENGINE

Description

ShipEngine is a REST API that simplifies shipping processes by integrating with multiple carriers, allowing users to manage shipping labels, track packages, and validate addresses efficiently.

Authentication Details

generic_api_key
stringRequired

Connecting to Shipengine

Create an auth config

Use the dashboard to create an auth config for the Shipengine toolkit. This allows you to connect multiple Shipengine accounts to Composio for agents to use.

1

Select App

Navigate to Shipengine.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Shipengine Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4shipengine_auth_config_id = "ac_YOUR_SHIPENGINE_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000"  # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10    # Replace this with a method to retrieve an API key from the user.
11    # Or supply your own.
12    user_api_key = input("[!] Enter API key")
13
14    connection_request = composio.connected_accounts.initiate(
15        user_id=user_id,
16        auth_config_id=auth_config_id,
17        config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18    )
19
20    # API Key authentication is immediate - no redirect needed
21    print(f"Successfully connected Shipengine for user {user_id}")
22    print(f"Connection status: {connection_request.status}")
23    
24    return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, shipengine_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Shipengine toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["SHIPENGINE"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17    completion = openai.chat.completions.create(
18        model="gpt-4o",
19        messages=[
20            {
21                "role": "user",
22                "content": task,  # Your task here!
23            },
24        ],
25        tools=tools,
26    )
27
28    # Handle Result from tool call
29    result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30    print(f"[!] Completion: {completion}")
31    print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Create Package Type

Description

Tool to create a new custom package type. Use after defining package dimensions and weight.

Action Parameters

dimensions
objectRequired
name
string
package_code
stringRequired
weight
objectRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Tag

Description

Tool to create a new tag in ShipEngine. Use after determining the desired tag name for shipments.

Action Parameters

tag_name
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Warehouse

Description

Tool to create a new warehouse. Use when adding a new inventory location after verifying its full address details.

Action Parameters

is_default
boolean
origin_address
objectRequired
return_address
object
warehouse_name
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Webhook

Description

Tool to create a ShipEngine webhook. Use when you need to register a webhook for specific events. Use after confirming your event-handling endpoint is ready.

Action Parameters

enabled
booleanDefaults to True
event
stringRequired
url
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Shipment by ID

Description

Tool to retrieve a shipment by ID. Use when you need detailed shipment information after creation.

Action Parameters

shipment_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Batches

Description

Tool to list all batches. Use when you need to retrieve batches with optional filters, sorting, or pagination. Call after creating or updating batches.

Action Parameters

batch_status
string
page
integerDefaults to 1
page_size
integer
sort_by
string
sort_dir
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Labels

Description

Tool to list all shipping labels. Use when you need to retrieve labels with optional filters and pagination. Call after label creation or to monitor shipments.

Action Parameters

carrier_id
string
created_at_end
string
created_at_start
string
label_status
string
page
integerDefaults to 1
page_size
integerDefaults to 50
service_code
string
ship_date_end
string
ship_date_start
string
tracking_number
string
warehouse_id
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Manifests

Description

Tool to list all manifests. Use when you need to retrieve a paginated list of manifests with optional filters.

Action Parameters

created_at_end
string
created_at_start
string
page
integerDefaults to 1
page_size
integer
status
string
voided
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Packages

Description

Tool to list all package types. Use when selecting package options before shipment creation.

Action Parameters

page
integerDefaults to 1
page_size
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Shipments

Description

Tool to list shipments with optional filters. Use after creating shipments to retrieve or monitor shipments.

Action Parameters

carrier_id
string
created_at_end
string
created_at_start
string
modified_at_end
string
modified_at_start
string
page
integerDefaults to 1
page_size
integerDefaults to 50
recipient_name
string
sales_order_id
string
service_code
string
ship_date_end
string
ship_date_start
string
sort_by
string
sort_dir
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Tags

Description

Tool to list all tags. Use when you need to retrieve all tags associated with your account.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Warehouses

Description

Tool to list all warehouses. Use when you need to retrieve warehouse locations with pagination. Call after creating or updating warehouses.

Action Parameters

page
integerDefaults to 1
page_size
integerDefaults to 25

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Webhook Events

Description

Retrieve a list of available webhook event types.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Validate Address

Description

Tool to validate and normalize shipping addresses. Use after collecting raw addresses to ensure they are correct and standardized before shipping.

Action Parameters

addresses
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired