StarShipIt MCP

Add a new address entry to the StarShipIt address book for reuse in future orders. **When to use:** Use this when a contact's details need to be saved for repeated use — e.g. a frequent supplier, warehouse, or customer. Once saved, addresses can be retrieved via `starshipit_list_addresses` and assigned to orders without re-entering details. **Required fields:** - `name` — full name of the contact - `street` — street address - `post_code` — postcode - `country` — country name (e.g. "Australia") or ISO code (e.g. "AU") **Optional fields:** - `code` — your custom reference code for quick lookup - `company`, `suburb`, `city`, `state` - `phone`, `email` - `instructions` — courier delivery instructions - `building` — building name or apartment number - `carrier` — preferred carrier ID (0 = no preference) - `signature_required` — whether delivery requires a signature **Returns:** The newly created address object including its assigned `id`. **Errors:** - 400 — missing required fields (name, street, post_code, country) or validation failure - 409 — address with the same code may already exist - 401/403 — authentication failure **Example:** ```json { "address": { "code": "MELB-WH", "name": "Warehouse Manager", "company": "Acme Logistics", "street": "55 Bourke St", "suburb": "Melbourne", "city": "Melbourne", "state": "VIC", "post_code": "3000", "country": "Australia", "phone": "0398765432", "email": "warehouse@acme.com", "signature_required": false } } ```

Add a new product to the StarShipIt product catalogue. Products in the catalogue are used to auto-populate line item details (weight, dimensions, customs info) when creating orders. Adding a product here means it can be matched by SKU when orders are imported. **Required fields (within the `product` object):** - `sku`: Unique Stock Keeping Unit identifier. Must be unique across the catalogue. - `title`: Human-readable product name. **Optional fields (all within the `product` object):** - `customs_description`: Description for customs declarations (for international shipments) - `description`: Internal product description - `country`: Country of origin (ISO code or name) - `weight`: Weight in kg - `height`, `length`, `width`: Dimensions in metres - `hs_code`: Harmonised System tariff code (e.g. "6109.10") - `mid`: Manufacturer ID code (used for US customs) - `price`: Declared value for customs - `dangerous_goods`: Boolean flag if the product contains DG - `barcode`, `bin_location`, `brand`, `color`, `size`, `material`, `model`, `usage` **Returns:** The created product object including its new `id`. **Error cases:** - 400: Missing required fields (sku or title) or invalid field values - 409: A product with this SKU already exists **Use this tool when:** - Adding new SKUs to the catalogue before importing orders - Seeding product data for customs auto-fill on international shipments

Archive an order in StarShipIt. Archived orders are hidden from the main fulfilment queue but remain in the system and can be restored at any time. **When to use:** Use this instead of deleting when you want to remove an order from the active queue while retaining its record for auditing, reporting, or potential restoration. **Parameters:** - `order_id` (required) — StarShipIt internal order ID to archive **Returns:** Confirmation message on success. **Errors:** 404 if order not found; 401 if API keys invalid.

Reassign orders between StarShipIt accounts using API keys. Use this to move orders from one StarShipIt sub-account or warehouse account to another. **When to use:** Use in multi-account or multi-warehouse setups where orders need to be routed to a specific fulfilment account after initial import. **Parameters:** - `orders` (required) — Array of assignment instructions, each containing: - `order_id` (required) — The order ID to reassign - `current_api_key` (required) — API key of the account currently holding the order - `new_api_key` (required) — API key of the destination account **Returns:** Confirmation of how many orders were reassigned. **Errors:** 400 if any entry is malformed; 401 if any API key is invalid; 403 if you lack permission to access the source or destination account; 404 if any order not found.

Apply the same carrier or shipping service product to a batch of orders in StarShipIt. Use this to reassign carrier/service for multiple orders in a single call. **When to use:** Use when you want to reassign the same carrier or product code across many orders at once — e.g. after a carrier rate change or when bulk-selecting a service level in your fulfilment workflow. **Parameters:** - `order_ids` (required) — Array of StarShipIt order IDs to update (must not be empty) - `product_code` (optional) — Carrier service product code to assign (e.g. `"AUS_PARCEL_REGULAR"`) - `carrier_id` (optional) — Carrier identifier string to assign At least one of `product_code` or `carrier_id` should be provided alongside `order_ids`. **Returns:** Confirmation of how many orders were updated. **Errors:** 400 if `order_ids` is empty or payload is invalid; 404 if any order not found; 401 if API keys invalid.

Clone an existing shipment in StarShipIt, optionally converting it to a return shipment. **When to use:** Use this tool to duplicate an existing order — for example, to resend the same goods to the same recipient, or to create a return shipment (pre-paid return label) based on an outbound order. The cloned order is created in a pending/unshipped state and will need a label printed separately. **Parameters:** - `order_id` (required): The numeric StarShipIt order ID of the source shipment to clone. - `to_return_shipment` (optional): Set to `true` to create a return shipment from the original. The origin and destination addresses will be swapped. Defaults to `false` (standard clone). **Returns:** The newly created order record including its new order ID, order number, and carrier details. **Example success response:** ```json { "success": true, "order": { "order_id": 99999, "order_number": "CLONE-12345", "carrier": "AUSPOST" } } ``` **Error cases:** 400 if the order ID is invalid; 404 if the source order does not exist; 409 if the order cannot be cloned in its current state.

Create a new order in StarShipIt. The order will appear in the unshipped queue ready for label generation. **When to use:** Call this when a new order has been placed and needs to be imported into StarShipIt for fulfilment. **Parameters (all under `order` object):** - `order_number` (required) — Merchant order number (must be unique) - `destination` (required) — Recipient address (name, street, post_code, country are required) - `order_date` (optional) — ISO timestamp when the order was placed - `reference` (optional) — Secondary reference (e.g. customer PO) - `carrier` / `carrier_name` (optional) — Pre-assign a carrier - `shipping_method` (optional) — Service level (e.g. "Express") - `signature_required` (optional) — Require signature on delivery - `return_order` (optional) — Mark as a return order - `items` (optional) — Array of line items - `packages` (optional) — Array of package dimensions/weights **Returns:** Created Order object with assigned `order_id`. **Errors:** 400 if required fields missing or invalid; 409 if order_number already exists; 401 if API keys invalid.

Import multiple orders into StarShipIt in a single API call. Use this for batch fulfilment import from external systems. **When to use:** Use instead of calling `starshipit_create_order` in a loop when you have many orders to import at once. More efficient and rate-limit-friendly. **Parameters:** - `orders` (required) — Array of order objects (same shape as `starshipit_create_order`). Each must include `order_number` and `destination`. **Returns:** Summary of created orders including any per-order failures with error details. **Errors:** 400 if any order payload is malformed; 409 if any order number already exists; 401 if API keys invalid.

Create tracking-only orders in StarShipIt for shipments dispatched outside the platform. **When to use:** Use this tool when you have shipments that were booked or dispatched through a carrier directly (not via StarShipIt) and you want to import them into StarShipIt to enable centralised tracking, notifications, and reporting. At least one of `name` or `order_number` should be provided per order entry. **Parameters:** - `orders` (required): Array of tracking order objects to create. Each object requires: - `carrier` (required): Carrier code for the shipment (e.g. `"AUSPOST"`, `"DHL"`, `"UPS"`). - `tracking_number` (required): The carrier-assigned tracking number (e.g. `"1Z999AA10123456784"`). - `name` (optional but recommended): Recipient or customer name associated with the shipment. - `order_number` (optional but recommended): Your internal order/reference number. **Note:** At least one of `name` or `order_number` must be supplied per entry to make tracking orders identifiable in the StarShipIt dashboard. **Returns:** An array of created order records, each with the new StarShipIt order ID, order number, tracking number, and carrier. Individual entries that fail will include an `error` field. **Example success response:** ```json { "success": true, "orders": [ { "order_id": 55001, "order_number": "ORD-9901", "tracking_number": "1Z999AA10123456784", "carrier": "UPS" }, { "order_id": 55002, "order_number": "ORD-9902", "tracking_number": "EJ123456789AU", "carrier": "AUSPOST" } ] } ``` **Error cases:** 400 if carrier or tracking_number is missing for any entry; 409 if a tracking number already exists in the platform.

Delete one or more addresses from the StarShipIt address book by their IDs. This action is permanent and cannot be undone. **When to use:** Call this to remove outdated, duplicate, or unwanted address entries. You can delete multiple addresses in a single call by passing an array of IDs. **CAUTION:** Deletion is irreversible. Verify the IDs with `starshipit_list_addresses` before calling this tool. **Parameters:** - `address_ids` — non-empty array of integer address book IDs to delete **Returns:** A success confirmation. If any ID does not exist, the API may still return success for the IDs that were found. **Errors:** - 400 — empty array or invalid ID format - 401/403 — authentication failure **Example — delete two addresses:** ```json { "address_ids": [81692357, 81692358] } ``` **Workflow tip:** Always call `starshipit_list_addresses` with a search_term first to confirm which IDs you want to delete before proceeding.

Permanently delete an order from StarShipIt. This action is irreversible — the order will be removed from the system entirely. **When to use:** Only use on unshipped orders that were created in error and must be removed. For orders you want to retain but hide from the queue, use `starshipit_archive_order` instead. **Parameters:** - `order_id` (required) — StarShipIt internal order ID to permanently delete **Returns:** Confirmation message on success. **Warning:** This is a destructive, permanent action. The order cannot be recovered after deletion. **Errors:** 404 if order not found; 409 if the order has already been shipped (cannot delete shipped orders — use archive instead); 401 if API keys invalid.

Delete one or more products from the StarShipIt product catalogue. This operation is irreversible. **Two modes:** 1. **Delete specific products** (recommended): Provide an array of numeric `product_ids`. Only those products are deleted. Leave `all_products` as `false` (default). 2. **Delete ALL products** (use with extreme caution): Set `all_products: true` and pass an empty `product_ids` array `[]`. This permanently removes every product in the catalogue — there is no undo. **Parameters:** - `product_ids`: Array of numeric product IDs to delete. Use an empty array `[]` only when `all_products` is `true`. - `all_products`: Set to `true` to delete the entire catalogue. Defaults to `false`. If `true`, `product_ids` is ignored. **Returns:** - `success`: Whether the deletion succeeded - `deleted_count`: Number of products deleted (if returned by API) - `errors`: Any per-product errors **Error cases:** - 400: Invalid product IDs or malformed request body - 404: One or more product IDs not found (partial deletes may still succeed) **Use this tool when:** - Removing discontinued products from the catalogue - Purging test/dummy products after setup - Clearing the entire catalogue before a fresh import (all_products=true — use carefully)

Get available delivery services (carrier + service options) for a specific order or a general route. Returns service codes that are directly usable when creating or updating orders. **When to use:** Prefer this over `starshipit_get_rates` when: - You have an existing order (`order_id`) and need the services available for it - You want to populate a dropdown or list of services that a user can select (the returned `service_code` values map directly to the StarShipIt order field) - You need a fresh rate lookup — pass `refresh_rate: true` to bypass any cached result **Parameters:** - `order_id` (optional) — existing order ID to fetch services for; if omitted, sender/destination/packages are used - `refresh_rate` (optional, default false) — set `true` to force a live carrier rate lookup instead of returning cached data - `sender`, `destination`, `packages` — same shape as `starshipit_get_rates`; required when `order_id` is not provided **Returns:** An array of service objects, each with: - `carrier` / `carrier_name` — carrier identifier and display name - `service_name` / `service_code` — description and the code to pass to order create/update - `total_price` — quoted price - `pricing_breakdown` — price ex GST, GST, and estimated delivery days (JSON format) **Errors:** - 400 — missing required fields or invalid address/package data - 404 — order_id not found - 401/403 — authentication failure **Example — get services for an existing order:** ```json { "order_id": 100000, "refresh_rate": true } ``` **Example — get services for a new route:** ```json { "sender": { "street": "10 Geonic Street", "suburb": "Woodridge", "state": "QLD", "post_code": "4114", "country_code": "AU" }, "destination": { "street": "10 Geoffrey Place", "suburb": "Mangere East", "city": "Auckland", "post_code": "2024", "country_code": "NZ" }, "packages": [{ "weight": 1.2 }] } ```

Retrieve manifest documents (PDF, XML, etc.) as base64 file content. Each manifest can have one or more associated document files that you submit to the carrier at pickup. The markdown format lists file names and sizes. The full base64 content is always in structuredContent; the JSON text output is capped at 25000 characters. **Query parameters:** - `manifest_id` (optional): Filter to files for a specific manifest. Omit to list files across all manifests. - `limit`: Max results per page (default 50, max 250) - `page`: Page number (default 1) **Returns:** - `files`: Array of `{ file_name, file_data }`, where `file_data` is the base64 file content **Error cases:** - 404: Manifest ID not found - 401/403: Invalid or missing API credentials **Use this tool when:** - Downloading a manifest PDF to hand to a carrier driver - Retrieving document URLs for a specific manifest ID - Listing all available manifest documents

Retrieve a single order from StarShipIt by its internal ID or merchant order number. At least one of `order_id` or `order_number` must be supplied. **When to use:** Use when you need the full detail of a specific order — destination, items, packages, carrier assignment, and metadata. **Parameters:** - `order_id` (optional) — StarShipIt internal numeric order ID - `order_number` (optional) — Merchant-assigned order number / reference (e.g. `"#1001"`) At least one of `order_id` or `order_number` must be provided. **Returns:** Full Order object. **Example response (JSON):** ```json { "order": { "order_id": 12345, "order_number": "#1001", "carrier": "AUSPOST", "destination": { "name": "Jane Smith", "street": "1 Test St", "post_code": "3000", "country": "Australia" } } } ``` **Errors:** 400 if neither identifier provided; 404 if order not found; 401 if API keys invalid.

Get a summary of orders filtered by status from StarShipIt. Useful for dashboards and reporting. **When to use:** Use when you need a status-specific count or listing for reporting, not fulfilment operations. Supports sorting and pagination. **Parameters:** - `order_status` (required) — Status to filter on (e.g. `"shipped"`, `"unshipped"`, `"delivered"`, `"archived"`) - `sort` (optional) — Sort field; refer to the StarShipIt API docs for supported values - `limit` (optional, default 50, max 250) — Number of results per page - `page` (optional, default 1) — Page number - `response_format` — `"markdown"` (default) or `"json"` **Returns:** Summary list of orders for the given status. Includes `has_more` flag. **Errors:** 400 if `order_status` is not a recognised value; 401 if API keys invalid.

Get available shipping rates (quotes) for a shipment between a sender and destination address with the given package dimensions. **When to use:** Call this before creating an order when you need to compare services by price. It is read-only and safe to call multiple times. **Required parameters:** - `sender` — pickup/origin address (street, suburb, post_code, country_code are required; city and state are optional but improve accuracy) - `destination` — delivery address (same shape as sender) - `packages` — array of package objects; each must have `weight` (kg); `height`, `width`, `length` (all in metres) are optional but recommended for volumetric pricing **Returns:** An array of rate objects, each with: - `service_name` / `service_code` — service description and machine-readable code (use service_code when setting a carrier on an order) - `total_price` — quoted price in the account currency **Errors:** - 400 — invalid address or package data (check post_code format and country_code) - 401/403 — authentication failure; verify API keys - No rates returned — the origin/destination combination may not be supported by any connected carrier **Example request body:** ```json { "sender": { "street": "184 Exhibition St", "suburb": "Melbourne", "post_code": "3000", "country_code": "AU", "state": "VIC" }, "destination": { "street": "20 Liverpool St", "suburb": "Paddington", "post_code": "2021", "country_code": "AU", "state": "NSW" }, "packages": [{ "weight": 0.5, "length": 0.3, "width": 0.2, "height": 0.1 }] } ```

Get a list of orders that StarShipIt suggests can be merged — typically orders from the same customer with the same destination address. Use this before calling `starshipit_merge_orders` to identify candidates. **When to use:** Run this during order processing to find consolidation opportunities that reduce shipping costs and packaging. **Parameters:** - `limit` (optional, default 50, max 250) — Number of result groups per page - `page` (optional, default 1) — Page number - `response_format` — `"markdown"` (default) or `"json"` **Returns:** List of mergeable order groups. Each group identifies a suggested parent order and associated child orders. Includes `has_more` flag. **Errors:** 401 if API keys invalid.

List saved addresses from the StarShipIt address book, with optional text filtering and pagination. **When to use:** Use this to: - Look up an existing contact before creating an order (avoids re-entering addresses) - Search for a specific company or person's delivery details - Browse all saved addresses for account management **Parameters:** - `search_term` (optional) — filters by name, company, street, suburb, city, or postcode; leave blank to list all - `limit` (default 50, max 250) — number of addresses per page - `page` (default 1) — page number for pagination; increase to load more results **Returns:** An array of address objects, each containing: - `id` — unique address book ID (required for update/delete) - `code`, `name`, `company` - Full address: `street`, `suburb`, `city`, `state`, `post_code`, `country` - Contact info: `phone`, `email` - Delivery preferences: `instructions`, `building`, `carrier`, `signature_required` **Pagination:** If `total_records` is greater than `limit × page`, increment `page` to retrieve more results. **Errors:** - 401/403 — authentication failure - Empty result — no addresses match the search term or the address book is empty

List delivered orders from StarShipIt. Returns orders where the carrier has confirmed delivery. **When to use:** Use for post-delivery reporting, customer-service lookups, or reconciliation workflows. **Parameters:** - `order_ref` (optional) — Filter by order reference string; useful for looking up a specific customer's deliveries - `response_format` — `"markdown"` (default) or `"json"` **Returns:** List of delivered Order objects including carrier and destination details. **Errors:** 401 if API keys invalid.

List all manifests in your StarShipIt account. Manifests group shipments that have been closed/submitted to a carrier. A manifest is created when you "manifest" a set of shipments, signalling to the carrier that they are ready for collection. **Returns:** Manifest ID, name, date, carrier ID, and the number of consignments and articles in each manifest. **Example response fields:** - `id`: Unique identifier for the manifest - `name`: Manifest name - `date`: ISO 8601 timestamp of the manifest - `carrierId`: Numeric carrier ID - `numberConsignments` / `numberArticles`: Counts in the manifest - `total_count` / `total_pages`: Pagination totals **Pagination:** Use `limit` (max 250) and `page` to page through results. **Error cases:** - 401/403: Invalid or missing API credentials **Use this tool when:** - Reviewing past manifests for a carrier - Looking up a manifest ID before downloading its PDF - Auditing which shipments have been submitted to carriers

List printed (label generated) orders from StarShipIt. Use this to review orders where labels have been printed but may not yet be manifested. **When to use:** Use to audit recently-printed shipments or find orders still awaiting manifesting before a carrier pickup. **Parameters:** - `status` (optional, default `"recently_printed"`) — Filter by shipment status: - `recently_printed` — labels printed recently - `unmanifested` — printed but not yet manifested - `since_created_date` (optional) — Only return shipments created after this ISO timestamp - `limit` (optional, default 50, max 250) — Number of results per page - `page` (optional, default 1) — Page number - `response_format` — `"markdown"` (default) or `"json"` **Returns:** List of Shipment/Order objects including tracking numbers and carrier info. Includes `has_more` flag. **Errors:** 401 if API keys invalid; 400 if `status` value is not recognised.

List or search products in the StarShipIt product catalogue. Products are pre-configured items used to auto-populate order line items when creating orders. Each product can carry customs details (HS code, country of origin, customs description) and physical dimensions for accurate rate calculations. **Query parameters:** - `search_term`: Free-text search across SKU, title, barcode, and description. Pass an empty string `""` to list all products without filtering. - `page_number`: Page number for pagination (default: 1) - `page_size`: Number of results per page (min: 10, max: 2000, default: 50) - `skip_records`: Number of records to skip (offset). Useful for offset-based pagination alongside `page_size`. Default: 0. - `sort_column`: Column to sort by. One of: Sku | Barcode | BinLocation | Brand | Colour | Country | CustomsDescription | DangerousGoods | Description | HsCode | Mid | Price | Size | Title | Weight (default: Sku) - `sort_direction`: Ascending or Descending (default: Ascending) **Note:** This API uses `page_number`/`page_size`/`skip_records` rather than the standard `page`/`limit` pagination used by other StarShipIt endpoints. **Returns per product:** - SKU, title, id, brand, barcode, bin_location, country, weight, dimensions (length/width/height in metres), hs_code, mid, price, dangerous_goods flag, colour, size, material, model, usage, customs_description, description **Example return fields:** ```json { "id": 12345, "sku": "WIDGET-001", "title": "Blue Widget", "weight": 0.5, "hs_code": "8543.70", "country": "CN", "price": 9.99 } ``` **Error cases:** - 401/403: Invalid or missing API credentials - 400: Invalid query parameters (e.g. page_size out of range) **Use this tool when:** - Looking up a product by SKU or name before creating an order - Auditing the product catalogue for missing customs info - Checking dimensions/weights for rate calculation accuracy

List shipped orders from StarShipIt. Returns orders that have been manifested and dispatched to the carrier. **When to use:** Use to check dispatch history or to feed downstream tracking workflows. **Parameters:** - `since_shipped_date` (optional) — Only return orders shipped after this ISO 8601 timestamp - `limit` (optional, default 50, max 250) — Number of results per page - `page` (optional, default 1) — Page number - `response_format` — `"markdown"` (default) or `"json"` **Returns:** List of shipped Order objects with tracking numbers and carrier details. Includes `has_more` flag. **Errors:** 401 if API keys invalid.

List unshipped orders from StarShipIt. Returns orders that have been imported but not yet shipped. **When to use:** Call this to see your pending fulfilment queue. It is read-only and safe to call multiple times. **Parameters:** - `since_order_date` (optional) — Only return orders placed after this ISO 8601 timestamp (e.g. `"2024-01-01T00:00:00Z"`) - `since_last_updated` (optional) — Only return orders last updated after this ISO 8601 timestamp - `limit` (optional, default 50, max 250) — Number of results per page - `page` (optional, default 1) — Page number for pagination - `response_format` (optional) — `"markdown"` (default) or `"json"` **Returns:** List of Order objects including destination, items, packages, and carrier assignment. The response includes a `has_more` flag when further pages exist. **Example response (JSON):** ```json { "orders": [{ "order_id": 10001, "order_number": "#1001", "carrier": "AUSPOST", "destination": { "name": "Jane Smith", ... } }], "total": 120, "has_more": true, "page": 1 } ``` **Errors:** 401 if API keys are missing or invalid; 429 if rate-limited.

Manifest ALL unmanifested shipments for a specific carrier in one operation. This is a bulk operation that closes every shipment that is ready-to-manifest for the given carrier and creates a single manifest document for them. Use this at end-of-day or before carrier pickup when you want to submit everything at once. **Body parameters:** - `carrier` (required): The carrier identifier string. Common values: - `"AusPost"` — Australia Post - `"PlainLabel"` — Generic/plain label carrier - `"DHL"` — DHL Express - `"StarTrack"` — StarTrack - `"Fastway"` — Fastway / Aramex Check your StarShipIt account carrier settings for the exact identifier strings available. **Returns:** - `records_manifested`: Number of shipments manifested - `success`: Whether the manifest was created successfully - `errors`: Any errors encountered during manifesting **Error cases:** - 400: Invalid or unrecognised carrier name - 404: No unmanifested shipments found for this carrier - 409: Conflict — may already be manifested **Use this tool when:** - Performing an end-of-day manifest run for a specific carrier - You want to submit ALL pending shipments for a carrier at once rather than selecting individually

Manifest (close/submit) specific shipments to the carrier by their tracking numbers or order numbers. This closes the selected shipments and submits them to the carrier, creating a manifest document. After manifesting, shipments are locked and can no longer be edited. **Body parameters:** - `tracking_numbers` (required): Array of tracking numbers to manifest. Must not be empty. - `use_order_numbers` (optional): Set to `true` if the values in `tracking_numbers` are actually order numbers rather than carrier tracking numbers. Default: `false`. **Returns:** - `file_name`: Name of the manifest document - `pdf`: Base64 manifest PDF (JSON format only) - `success`: Whether the manifest was created successfully - `errors`: Any per-shipment errors (e.g. shipment already manifested) **Error cases:** - 400: Invalid or unrecognised tracking/order numbers - 409: One or more shipments already manifested - 422: Request body validation failure **Use this tool when:** - Closing a specific set of shipments for carrier pickup - You have a list of tracking numbers ready to hand to the carrier - You want to manifest a subset of shipments rather than all shipments for a carrier

Manifest (finalise/close) shipments by order IDs in StarShipIt. **When to use:** Use this tool to finalise and commit shipments to the carrier. Manifesting is typically done once at end-of-day or when a batch of orders is ready for carrier pickup. Once manifested, shipments cannot be easily reversed — ensure labels are correct before manifesting. **Important:** This operation is idempotent — manifesting already-manifested orders will not create duplicate manifests. **Parameters:** - `order_ids` (required): Array of numeric StarShipIt order IDs to include in the manifest. All orders must already have labels printed. **Returns:** The manifest document as a base64 PDF, with its label type. **Example success response:** ```json { "success": true, "label_type": "PDF", "pdf": "JVBERi0xLjQK..." } ``` **Error cases:** 400 if order IDs are invalid or orders do not have labels printed; 404 if orders do not exist; 409 if orders are in an incompatible state for manifesting.

Merge one or more child orders into a parent order in StarShipIt. After merging, the child orders are absorbed into the parent and the combined shipment will be dispatched as a single package. **When to use:** Use when a customer has placed multiple orders that should ship together in one box. Use `starshipit_get_suggested_merges` first to find recommended candidates. **Parameters:** - `parent_order_id` (required) — The order ID that will be kept as the merged result - `child_order_ids` (required) — Array of order IDs to merge into the parent (at least one) **Returns:** Confirmation of the merged order. **Warning:** This is a destructive operation — child orders will no longer exist as independent orders after the merge. **Errors:** 400 if `child_order_ids` is empty; 404 if any order ID not found; 409 if orders are not merge-compatible (e.g. different destination addresses); 401 if API keys invalid.

Print (or reprint) a shipping label for a single order in StarShipIt. **When to use:** Use this tool when you need to generate a carrier label for one specific order. If you are printing labels for multiple orders at once, prefer `starshipit_print_labels` for efficiency. **Parameters:** - `order_id` (required): The numeric StarShipIt order ID to print a label for. - `carrier` (optional): Carrier code to override the order's default carrier (e.g. `"AUSPOST"`, `"DHL"`). - `carrier_service_code` (optional): Carrier service code to override the order's default service (e.g. `"EXPRESS"`, `"PARCEL_POST"`). - `packages` (optional): Array of package dimensions/weights to use for the label. Each package has `weight` (kg, required), and optional `height`, `width`, `length` (all in metres). - `reprint` (optional): Set to `true` to reprint a previously generated label. Defaults to `false`. **Returns:** An object containing label URLs or base64-encoded label data for the order, along with the assigned tracking number, carrier, and service. On error, returns a descriptive error message. **Example success response:** ```json { "success": true, "labels": [ { "order_id": 12345, "tracking_number": "1Z999AA10123456784", "label_url": "https://cdn.starshipit.com/labels/label-12345.pdf", "carrier": "UPS", "carrier_service": "EXPRESS" } ] } ``` **Error cases:** 400 if the order ID is invalid or required order data is missing; 404 if the order does not exist; 409 if a label has already been printed and `reprint` is not set to `true`.

Print shipping labels for multiple orders at once in StarShipIt. **When to use:** Use this tool when you need to generate carrier labels for two or more orders in a single API call. For a single order, `starshipit_print_label` gives more control (carrier override, package dimensions). **Parameters:** - `order_ids` (required): Array of numeric StarShipIt order IDs to print labels for. Must contain at least one ID. - `reprint` (optional): Set to `true` to reprint previously generated labels for the specified orders. Defaults to `false`. **Returns:** An array of label results — one entry per order — each containing the label URL or base64-encoded label data, the assigned tracking number, carrier, and service. Individual orders that fail will include an `error` field while others may succeed. **Example success response:** ```json { "success": true, "labels": [ { "order_id": 101, "tracking_number": "TRACK001", "label_url": "https://cdn.starshipit.com/labels/label-101.pdf", "carrier": "AUSPOST" }, { "order_id": 102, "tracking_number": "TRACK002", "label_url": "https://cdn.starshipit.com/labels/label-102.pdf", "carrier": "AUSPOST" } ] } ``` **Error cases:** 400 if any order IDs are invalid or missing required order data; 404 if one or more orders do not exist; 409 if labels already exist and `reprint` is not `true`.

Generate packing slip documents for one or more orders in StarShipIt. **When to use:** Use this tool when warehouse staff need packing slips to pick, pack, and verify order contents before shipment. Packing slips do not require a label to have been printed first. **Parameters:** - `order_ids` (required): Array of numeric StarShipIt order IDs to generate packing slips for. Must contain at least one ID. **Returns:** A URL or base64-encoded PDF containing the packing slips for all specified orders. Multiple orders are typically combined into a single PDF document. **Example success response:** ```json { "success": true, "pdf_url": "https://cdn.starshipit.com/packingslips/slips-20240101.pdf" } ``` **Error cases:** 400 if order IDs are missing or invalid; 404 if one or more specified orders do not exist.

Replace an existing shipment in StarShipIt — voids the previous label and creates a new one. **When to use:** Use this tool when an existing label must be voided and replaced, such as when order details have changed after a label was printed (address correction, weight change, carrier change). This is a destructive operation: the previous label is voided with the carrier. **Warning:** This action voids the carrier label for the existing shipment. If the package has already been dispatched with that label, do NOT use this tool. Coordinate with the carrier directly in that case. **Parameters:** - `order_id` (required): The numeric StarShipIt order ID whose shipment label should be voided and replaced. **Returns:** The updated order record including the new label URL, new tracking number, carrier, and service details. **Example success response:** ```json { "success": true, "order": { "order_id": 12345, "order_number": "ORD-12345", "carrier": "DHL", "tracking_number": "NEWTRACK001", "label_url": "https://cdn.starshipit.com/labels/label-12345-v2.pdf" } } ``` **Error cases:** 400 if the order ID is invalid; 404 if the order does not exist; 409 if the order is manifested or already dispatched and cannot be replaced.

Restore a previously archived order in StarShipIt, returning it to the active fulfilment queue. **When to use:** Use to undo an `starshipit_archive_order` call, re-activating an order so it can be fulfilled. **Parameters:** - `order_id` (required) — StarShipIt internal order ID to restore from archive **Returns:** Confirmation message on success. **Errors:** 404 if order not found or not currently archived; 401 if API keys invalid.

Search orders in StarShipIt by a free-text phrase. Searches across order numbers, references, recipient names, tracking numbers, and other indexed fields. **When to use:** Use when you need to find a specific order but don't have the exact order_id. Supports partial matches. **Parameters:** - `phrase` (required) — Search string (e.g. order number, customer name, tracking number) - `limit` (optional, default 50, max 250) — Number of results per page - `page` (optional, default 1) — Page number - `response_format` — `"markdown"` (default) or `"json"` **Returns:** List of matching Order objects. Includes `has_more` flag when more pages exist. **Errors:** 400 if `phrase` is empty; 401 if API keys invalid; 429 if rate-limited.

Track a shipment by tracking number using StarShipIt. **When to use:** Use this tool to retrieve the current status, tracking events and carrier details for any shipment tracked through StarShipIt. This works for shipments created in StarShipIt as well as tracking-only orders imported via `starshipit_create_tracking_order`. **Parameters:** - `tracking_number` (required): The carrier tracking number to look up (e.g. `"1Z999AA10123456784"`). - `response_format` (optional): Output format — `"markdown"` (default) for a human-readable summary with formatted tracking events, or `"json"` for the raw API response suitable for programmatic use. **Returns:** Tracking status, order number and status, carrier name, service, shipment date, last update, carrier tracking URL, and a list of tracking events (date, status, details). **Example success response (markdown format):** ``` ## Tracking: 2XD198209601000935102 **Status:** In Transit **Order:** C12346 (Shipped) **Carrier:** Australia Post **Service:** 7B05 **Shipped:** 2024-04-17T12:52:05 **Tracking URL:** https://auspost.com.au/mypost/track/details/2XD198209601000935102 ### Tracking Events - **2024-04-17T13:20:18 — In Transit:** Item processed at facility ``` **Error cases:** 404 if the tracking number is not found in StarShipIt; 400 if the tracking number format is invalid.

Update an existing address book entry by its ID. **When to use:** Call this when a saved address needs to be corrected or updated — e.g. a contact has moved, changed phone number, or you need to add delivery instructions. Use `starshipit_list_addresses` first to find the correct `id`. **Parameters:** - `id` (required) — the address book entry ID to update (retrieve via `starshipit_list_addresses`) - `address` (required) — updated address fields; you should provide all fields, not just the changed ones, as the API replaces the entire entry **Required fields inside `address`:** - `name`, `street`, `post_code`, `country` **Optional fields inside `address`:** - `code`, `company`, `suburb`, `city`, `state` - `phone`, `email`, `instructions`, `building` - `carrier`, `signature_required` **Returns:** The updated address object. **Errors:** - 400 — validation failure on the address fields - 404 — no address with the given `id` was found - 401/403 — authentication failure **Example:** ```json { "id": 6926658, "address": { "name": "Warehouse Manager", "company": "Acme Logistics", "street": "55 Bourke St", "suburb": "Melbourne", "state": "VIC", "post_code": "3000", "country": "Australia", "phone": "0398765432", "signature_required": true } } ```

Update an existing unshipped order in StarShipIt. Only fields provided in the payload will be updated; others remain unchanged (partial patch semantics). **When to use:** Use to correct order data, change carrier or shipping method, update the destination address, or add/replace items/packages before a label is printed. **Parameters (all under `order` object):** - `order_id` (required) — StarShipIt internal order ID to update - All other fields from `starshipit_create_order` are optional **Returns:** Updated Order object. **Errors:** 400 if payload is invalid; 404 if order not found; 409 if order is already shipped (cannot update shipped orders); 401 if API keys invalid.

Update multiple existing orders in StarShipIt in a single API call. Each entry must include `order_id`; other fields are optional partial updates. **When to use:** Use to patch many orders at once — e.g. re-assigning carriers, correcting addresses in bulk, or adding packages to a batch of orders. **Parameters:** - `orders` (required) — Array of order update objects; each must include `order_id` plus any fields to change **Returns:** Summary of update results including any per-order errors. **Errors:** 400 if any payload is malformed; 404 if any order not found; 401 if API keys invalid.

Update an existing product in the StarShipIt product catalogue by its numeric ID. Use this to correct product details, update dimensions/weights, add customs codes, or change any other product attribute. The product `id` must be provided both at the top level and inside the `product` object — this is a StarShipIt API requirement. **Required top-level fields:** - `id`: Numeric product ID (obtain via `starshipit_list_products`) **Required `product` object fields:** - `id`: Same numeric product ID (must match top-level id) - `sku`: Product SKU (can be the existing SKU unchanged) - `title`: Product title (can be the existing title unchanged) **Optional `product` object fields:** All standard product fields (customs_description, country, weight, height, length, width, hs_code, color, size, barcode, bin_location, brand, usage, material, model, mid, price, dangerous_goods, description). **Returns:** The updated product object. **Error cases:** - 400: Validation errors (e.g. invalid field values) - 404: Product with given ID not found - 409: SKU conflict with another product **Use this tool when:** - Correcting product weight or dimensions after a measurement error - Adding missing HS codes to products before an international shipment - Updating a product price or customs description