Ship.com MCP Server

list_orders

Lists the orders in your account, newest first by order date. With no filter it returns the orders that are ready to ship, the unshipped work queue where rating and buying labels usually starts. Rows are compact; call get_order for an order's full detail.

Returns: orders, plus page and page_size as applied, total (all matching orders, not just this page) and status (the filter applied, as a status name or active). Each row has order_id (use it with the other tools in this section), order_number, name (the ship-to name stored on the order; may be empty), city, state, zip, country (US when blank), total, status and tracking_number.

Good to know: The filter takes a status name, but each row's status is the display label, so ready-to-ship rows read "Ready to ship", not ChooseShipping. active still includes finished orders, such as delivered and refunded ones. There is no date, customer or text-search filter. An unrecognized status returns an error that lists the accepted names, so send exactly one name, spelled as shown below. Rows are sorted by order date only and can shift if new orders import while you page. The row name is exactly what's on the order (a placeholder such as "Guest" shows as-is), so it can differ from ship_to.name in get_order.

Order statuses: filter by the name; results show the label.

Labels aren't unique: DeliveryFailureWait and WaitingForReturn both show as "Waiting for return", so filter by name. A canceled order's status name is Deleted.

{"status": "active", "page": 1, "page_size": 2}

get_order

Returns full detail for one order in your account: the ship-to address, totals, shipping and tracking fields, and line items. It works for an order in any status, including canceled and merged orders.

Returns: order_id, order_number, status (display label) and date (the order date); ship_to with name, company, street1, street2, city, state, zip, country (US when blank), phone and email; totals with subtotal, shipping (charged to your buyer), tax, total and weight_oz; shipping with method (the purchased label's carrier service), cost (what you paid for the label), ship_date and label_url, where method and label_url stay null until a label is bought (before then, cost can be null or hold an imported or estimated amount, so check label_url rather than cost); tracking_number and tracking_url (a Ship.com tracking page for labels bought through Ship.com); and items, one per line item, each with sku, upc, quantity and price.

Good to know: An ID that doesn't exist and an order in another account return the same error, Order {order_id} was not found in this account. Leaving out order_id returns order_id is required. Line items have no separate product name, style or size field. sku is the item code stored on the line, which can be null or, for some sales platforms, the product name. upc is often null and isn't always a real barcode: orders imported from some sales platforms carry a placeholder value there. price is the price recorded on the line; depending on where the order came from, it can be a unit price or a line total, so don't assume either. ship_to uses the order's saved shipping address when it has one. Otherwise it's built from the order, filling a missing or placeholder name (such as "Guest") and a missing email or phone from the customer's record, and uses "Current Resident" when no name can be found. company is often null. If a label is canceled, the order returns to "Ready to ship" and the label and tracking fields go back to null, though ship_date may keep the old date.

{"order_id": 4815162}

get_label

Returns the label files and tracking details for an order's purchased label. It returns stored links only, and never regenerates, re-buys or fetches anything from the carrier. Calling it for an order with no label isn't an error: you get has_label: false and null links.

Returns: order_id; label_url, the printable label formatted for your account's print setting (if your account prints by QR code, USPS labels come back as a scannable QR image instead of a label PDF); raw_label_url, the carrier's original 4x6 label file, present only for some carrier PDF labels (currently certain USPS labels) and null otherwise; form_url, a separate customs form PDF when the carrier provides one (currently UPS international shipments); receipt_url, a carrier receipt when the carrier provides one (currently UPS); tracking_number; tracking_url; and has_label, true when label_url is present.

Good to know: Use has_label to decide whether an order has a live label. Canceling a label clears label_url, tracking_number and tracking_url, but the other links can keep pointing at the voided label's files, so ignore raw_label_url, form_url and receipt_url when has_label is false. Label links are HTTPS file URLs; treat them as opaque rather than relying on their host or format. This tool works on every connection type and returns the label however it was bought, including in the Ship.com web app. Unknown IDs and other accounts' orders return the same not-found error as get_order.

{"order_id": 4815101}

track_order

Returns Ship.com's latest stored tracking status for an order. Ship.com keeps it updated automatically in the background; the tool doesn't query the carrier live, so calling it again won't refresh anything. An order without a label returns successfully with null tracking fields.

Returns: order_id; status, the order's display status, such as "In transit", "Delivered", "Delivery failure" or "Returned to sender" (an order status, not a raw carrier event); tracking_number; tracking_url; ship_date, in_transit_date, delivered_date and exception_date; exception, the carrier's exception text; and last_tracking_update, when Ship.com last stored a tracking update for the order, in UTC.

Good to know: Check last_tracking_update to see how fresh the data is. Not every background update sets it, so it can be null even after status has moved; treat null as "freshness unknown", not "never updated". Other timestamps carry no time zone. If a label is canceled, the status returns to "Ready to ship" and tracking_number, tracking_url and in_transit_date are cleared, but the other dates and exception can keep old values, so read status and tracking_number first. Unknown IDs and other accounts' orders return the same not-found error as get_order.

{"order_id": 4815101}

list_products

Lists the active products in your saved Ship.com product catalog, sorted by name from A to Z. Use it to look up product names, descriptions and prices when you build or edit an order. It reads your saved catalog only and doesn't pull products live from connected stores.

Returns: products, plus page and page_size as applied and total (all matching active products, not just this page). Each product has product_id, name, catalog (an optional grouping label), description and price.

Good to know: Inactive products never appear. Products are identified by name: results have no SKU, image, stock, cost or weight fields. Line items in get_order do carry a sku.

{"query": "candle", "page": 1, "page_size": 10}

create_order

Creates one new order at Ready to ship. Ship to a customer already in your address book with customer_id, or pass the recipient inline with ship_to to import an order from anywhere, such as a spreadsheet, an email or a marketplace. Add line items and a package weight now or later. Pass external_order_id so a retry or re-import returns the existing order instead of creating a duplicate.

Returns: created: true, order_id, a generated 6-character order_number, status ("Ready to ship"), the ship_to used and items_count. With items it adds subtotal (sum of price × quantity) and an equal total; with ship_to it adds customer_id and customer_created. weight_oz and external_order_id are echoed when you send them, and every result ends with a note. A duplicate re-send returns created: false, skipped_existing: true, the existing order's order_id, order_number and current status, and a note.

Good to know: Runs immediately. All input is checked before anything is saved, so a validation error creates nothing. No postage is charged and no carrier is contacted; the address is validated when you rate the order. Duplicate protection ignores canceled and merged orders, so a canceled import can be re-imported. A re-send isn't compared with the original and doesn't update it. The ID is kept in the order's notes as [ext:YOUR-ID], so replacing the notes with update_order turns duplicate protection off for that order. Send retries one at a time: two simultaneous calls with the same ID can both create an order. A catalog product matched by name (ignoring case) takes the new price and its cost resets to 0. If you run a rewards program, the order earns customer points as usual.

{"ship_to": {"name": "Maria Delgado", "street1": "1420 Maple Ave", "street2": "Apt 3B", "city": "Springfield", "state": "IL", "zip": "62704"}, "items": [{"name": "Lavender Soy Candle", "quantity": 2, "price": 18.50, "sku": "CND-LAV-08"}, {"name": "Gift Wrap", "price": 3.00}], "weight_oz": 22, "external_order_id": "SHOP-10482"}

bulk_create_orders

Creates up to 100 orders in one call. Each entry takes the same fields as create_order and goes through the same checks, including duplicate protection with external_order_id. One bad entry doesn't stop the rest: every entry gets its own result row, in input order, plus a summary. Use it instead of calling create_order in a loop.

Returns: results, one row per entry with index and ok. A successful row has order_id and order_number, plus skipped_existing: true when an existing order was returned; a failed row has error, the same message create_order would give. Also summary (created, skipped, failed) and a note. Rows don't include status, address or totals; use get_order for those.

Good to know: The whole call counts as one request against the rate limit of 60 requests per minute. There is no all-or-nothing: each entry is saved as it is processed. An external_order_id repeated inside the same batch is created once and reported as skipped on the later entry. Send numbers as JSON numbers: a value of the wrong type (such as "two" for a quantity) stops the whole call with an unexpected-error result after earlier entries were already saved. After any unexpected error, check with list_orders. Re-sending the same batch with an external_order_id on every entry is safe, because entries already created come back as skipped.

{"orders": [{"customer_id": 918274, "weight_oz": 8, "external_order_id": "SHOP-10483"}, {"ship_to": {"name": "Maria Delgado", "street1": "1420 Maple Ave", "street2": "Apt 3B", "city": "Springfield", "state": "IL", "zip": "62704"}, "items": [{"name": "Lavender Soy Candle", "quantity": 2, "price": 18.50}], "external_order_id": "SHOP-10482"}]}

update_order

Edits an order that is still at Ready to ship or an earlier status: notes, display order number, the amounts you charge your customer, line items and package weight. Send only the fields you want to change, at least one. The total is recalculated every time as subtotal - discount + tax + shipping + handling, using the saved value for any amount you don't send.

Returns: updated: true, order_id, order_number, totals (subtotal, shipping, tax, discount, handling, total), plus items_count and weight_oz when you sent them, and a note.

Good to know: Runs immediately and doesn't change the order's status. Rates you got before the change still carry the old weight; call get_rates again before buying. Amounts are saved as sent and aren't range-checked. Items update your General product catalog the same way create_order does. Replacing the notes on an order created with external_order_id removes its [ext:...] reference and with it duplicate protection; include that reference in the new notes to keep it. If you run a rewards program, the customer's points are recalculated. Invoices can't be created or sent through MCP; use the Ship.com app for those.

{"order_id": 4821937, "items": [{"name": "Lavender Soy Candle", "quantity": 3, "price": 18.50, "sku": "CND-LAV-08"}], "shipping": 6.95, "tax": 3.30, "discount": 5.00, "weight_oz": 30}

update_order_address

Changes the ship-to street address on an order that is still at Ready to ship or an earlier status. The new address is validated before it is saved; if it doesn't validate, nothing changes. Only this order is updated: the customer's address-book entry and the recipient's name, company, phone and email stay as they are.

Returns: updated: true, order_id, the saved ship_to (street1, street2, city, state, zip, with the corrected city, state and ZIP) and a note.

Good to know: Runs immediately. Rates you got before the change still carry the old address; call get_rates again before buying. US addresses only: the address is always validated as a US address. If the validation service is briefly unavailable you get the same "could not validate" error, so a later retry may succeed.

{"order_id": 4821937, "street1": "1420 Maple Ave", "street2": "Apt 3B", "city": "Springfield", "state": "IL", "zip": "62704"}

cancel_order

Cancels an order entirely. Its status becomes Canceled and it stays visible in your account. If the order hasn't shipped yet and its label is within 29 days of its ship date, the label is voided first, with the same refund handling as cancel_shipping_label. Customer reward points earned on the order are reversed. To void only the label and keep the order open, use cancel_shipping_label instead.

Returns: A preview returns preview: true, order_id, current_status (for example "Label purchased"), would_void_label, would_reverse_reward_points, refund_note and note. A confirmed call returns canceled: true, order_id, status ("Canceled"), label_voided, postage_balance (your current balance, not a credit from this call) and refund_note (null when there was no label).

Good to know: Call it once without confirm to see what will happen, then again with confirm: true. A label isn't voided once the order is in transit, delivered or being returned, or when the label is more than 29 days past its ship date; the label and tracking then stay on the canceled order and no postage refund is issued. For an order that already shipped, the refund note may describe this as no label to void or as outside the void window. If the carrier refuses the void, the order is still canceled, label_voided is false and no refund is queued; contact help@ship.com if you expected one. would_reverse_reward_points is always true in a preview, even when the order earned no points. The cancellation isn't sent to connected sales platforms; only a voided label sends a tracking update. Cancel each order once. A canceled order can be imported again with create_order using the same external_order_id.

{"order_id": 4821937, "confirm": true}

cancel_shipping_label

Voids a purchased shipping label and returns the order to Ready to ship, so you can edit or re-rate it. A label can be voided within 29 days of its ship date. The postage refund isn't immediate: it typically posts to your Ship.com postage balance about 14 days after the void, and is subject to the carrier accepting the void.

Returns: A preview returns preview: true, order_id, tracking_number, ship_date, within_void_window, shipping_cost, refund_note and note. A confirmed call returns canceled: true, order_id, status ("Ready to ship") and refund_note.

Good to know: A label past the 29-day window returns an error instead of a preview. When the void goes through, the tracking number, label, rate and insurance are cleared and insurance bought with the label is voided. Unsent follow-up emails to your customer that were triggered by the printed label are canceled. The order leaves any scheduled pickup, but the pickup itself stays booked. If the order came from a connected sales platform that syncs tracking, the change is sent there. When the refund comes due, the label cost and any insurance fee are credited to your postage balance, even if you paid by card, and you get a confirmation email. If the carrier has scanned the package by then, no credit is issued and the tracking number is restored. If the carrier refuses the void, most often because the package is already in transit, nothing changes and no refund is queued. The carrier gives no reason, and a retry the same day may be refused again. Contact help@ship.com if the label should have been refundable. Return labels aren't handled by this tool.

{"order_id": 4821937, "confirm": true}

quote_shipping

Gets shipping rates for a destination without an order, for example to estimate what a package will cost. Every call gets live carrier quotes and skips the short-lived rate cache; Flat Rate prices follow a USPS price list that is refreshed daily. Nothing is saved and no money moves. To buy a label you need an order: use get_rates and buy_label.

Returns: destination (zip and country, after the US default), weight_oz, rates and, when present, warning. Each rate row has method (display name, such as "USPS Ground Advantage"), rate_id, service_level (usps_ground_advantage, usps_priority, usps_priority_express, usps_intl_express, usps_intl_priority, usps_intl_first_class_package, or a UPS service code such as "03" Ground, "01" Next Day Air, "02" 2nd Day Air, "93" Ground Saver or "11" Standard), rate (what your account pays, including any per-label charge your plan adds), retail_rate (retail price for comparison, or null), delivery_date (the carrier's estimate as an ISO date-time without a time zone; always null on UPS rows), is_cubic, and variant and max_weight_oz (set on Ground Advantage weight-band rows, such as "up to 12 oz" and 12; otherwise null).

Good to know: Rows come in a fixed order: Priority Mail Flat Rate products, then Priority Mail, Priority Mail Express (shown as "USPS Express Mail") and Ground Advantage, then the Ground Advantage weight bands, then international USPS services, then UPS. Options that didn't price are left out, and similar rows aren't merged: Ground Advantage can appear twice, once as a cubic row ("(Cubic)" or "(Cubic Soft Pack)" in method) and once plain. Weight-band rows whose limit is below your weight are dropped, and so are all band rows when a side is over 22 inches or the volume is over 1,728 cubic inches. UPS rows can appear before your account is registered with UPS, but buying a UPS label requires register_ups. A weight without dimensions can quote lower than the carrier later bills, because dimensional charges come back as postage adjustments, so give real dimensions when you have them. One package per call, shipping today, with no signature, Saturday delivery or package-type options. Errors: "zip is required.", "weight_oz must be greater than 0.", the ship-from error, or "Rating failed: " with the carrier's message when nothing priced.

{"zip": "30309", "weight_oz": 12, "length": 10, "width": 8, "height": 4}

get_rates

Gets shipping rates for one of your orders, using the order's ship-to address and your ship-from address. It returns a package_id and a list of priced options. To buy one, pass that option's rate_id, method and service_level, plus the package_id, into buy_label exactly as returned. You can override the package weight and dimensions.

Returns: order_id, package_id (an opaque token for buy_label), ship_date (ISO date-time in UTC), rates (the same row fields as quote_shipping), a note reminding you to pass the chosen values into buy_label verbatim, and warning when present.

Good to know: Without a weight you get only the fixed-price options: the six Priority Mail Flat Rate products and the four Ground Advantage weight bands, minus any band below the order's saved weight (an order saved above 15.9 oz may get only Flat Rate rows). To see Priority Mail, Priority Mail Express, Ground Advantage at the real weight, UPS and international services, pass a positive weight_oz. Flat Rate box and weight-band prices may be served from a rate cache for up to 3 hours, and Flat Rate prices follow a USPS price list that is refreshed daily.

It never buys anything or moves money, but like rating in the Ship.com web app it saves to the order: a positive weight_oz becomes the order's package weight, and for US destinations the ship-to address is checked with carrier address validation and the result is stored on the order. A valid address can have its city and state corrected. Nothing is saved when the validation service is unavailable. It's annotated read-only in tools/list because it never purchases.

Choose a Ground Advantage weight-band row only if the package weighs no more than its max_weight_oz. The label is bought at the band's weight and a standard box size, so a heavier or larger package is billed the difference later as a postage adjustment. Bands that can't fit are dropped when the weight or dimensions are known; with neither known, all four come back. UPS rows can appear before your account is registered with UPS (buying one needs register_ups), and a PO Box destination gets only UPS Ground Saver from UPS.

An order that doesn't exist or isn't yours returns "Order <id> was not found in this account." A destination that fails address validation returns "Rating failed: the destination address failed validation. Correct it with update_order_address before buying a label." (see update_order_address). Shipments that need a customs declaration can't be rated or bought through MCP yet: destinations outside the US; APO, FPO and DPO addresses; US territories and freely associated states (Guam, the U.S. Virgin Islands, American Samoa, the Northern Mariana Islands, Micronesia, the Marshall Islands and Palau); and any order when your own ship-from address is APO, FPO or DPO. Ship those from the Ship.com web app. One package per order per call, with no signature, Saturday delivery, return label or custom package options.

{"order_id": 48213, "weight_oz": 14, "length": 10, "width": 8, "height": 4}

Response (tokens shortened). package_id is shared by every row; rate_id, method and service_level come from the row you choose. Weight-band rows set variant and max_weight_oz:

{
  "order_id": 48213,
  "package_id": "eyJhbGciOi...",
  "ship_date": "2026-10-05T14:02:11Z",
  "rates": [
    {"method": "USPS Ground Advantage", "rate_id": "eyJhbGciOi...", "service_level": "usps_ground_advantage", "rate": 7.42, "retail_rate": 9.35, "delivery_date": "2026-10-08T00:00:00", "is_cubic": false, "variant": null, "max_weight_oz": null},
    {"method": "USPS Priority", "rate_id": "eyJhbGciOi...", "service_level": "usps_priority", "rate": 10.15, ...}
  ],
  "note": "Pass a chosen rate's rate_id + this package_id + its method + service_level verbatim into buy_label."
}

buy_label

Buys a real USPS or UPS shipping label for an order, paid from your postage balance. Pass the values from get_rates exactly as returned. Without confirm it returns a preview of the price, your balance and whether an auto-recharge would run, and buys nothing. Call again with confirm: true to purchase.

Returns: A preview returns preview: true, order_id, method, service_level, price (postage), pay_as_you_go_fee, insurance, insured_value, insurance_cost, total_charge, current_balance, balance_after, balance_would_go_negative, auto_recharge_amount, auto_recharge_would_fire and a message. A purchase returns purchased: true, order_id, cost (postage), insurance, insured_value, insurance_cost, label_url (Full Size: a 4x6 label on a US Letter page), tracking_number, tracking_url (https://app.ship.com/tracker/ plus the tracking number), form_url (a customs form when one applies, otherwise null), balance_after, a message, status (the order's status, normally "Label purchased") and next_step. While the label is unprinted, next_step says to mark it printed once it's printed, then book a pickup if your plan includes carrier pickup or drop it off; for a UPS label it points to the paid UPS pickup in the Ship.com web app. Otherwise it's null.

Good to know: Available on access-token connections. It is not offered on connections authorized through Ship.com sign-in (OAuth), such as the Claude directory connector and claude.ai custom connectors; there it is absent from tools/list, and a call returns JSON-RPC error -32602 saying the tool is not available. Confirm doesn't need an earlier preview, and the preview doesn't check package_id, plan limits, billing, ship date, address or account standing, so a clean preview can still fail on confirm.

Postage comes out of your postage balance, plus a $0.30 pay-as-you-go fee when your auto-recharge amount is $0.01 or less. Insurance is a separate charge: $0.99 for each $100, or part of $100, of insured value on orders to the US ($40 costs $0.99, $120 costs $1.98), and $1.25 per $100 otherwise. If your balance can't cover postage and insurance, your payment method on file is charged before the label is created, for the larger of your auto-recharge amount and the shortfall. With an auto-recharge amount of $0.01 (pay as you go), the charge is the shortfall plus $0.30, at least $1, and the preview's auto_recharge_would_fire still reads false. With an amount of $0, the purchase fails instead. A recharge stays on your balance even if the purchase then fails, for example at your plan's monthly shipment limit.

On success the order moves to Label purchased with its tracking number and label saved. It moves to Label printed when it's printed from the Orders page or a batch's purchase page in the Ship.com web app. Labels printed straight from label_url, or with Ship Mode's print-all, need a call to mark_labels_printed once they're printed. Carrier pickups collect printed labels only (see Pickups). An order still awaiting payment is marked as paid outside Ship.com. The tracking number is sent to the order's sales platform, such as Shopify, Etsy, eBay, WooCommerce, Square, Squarespace, Wix or PayPal. Customer emails and tracking webhooks go out later, when the label is marked printed. Your saved label format is set to Full Size. If the order already has a label, that label is returned and nothing is charged; the response still shows purchased: true, with cost from the rate you passed. Simultaneous purchases for one order return the first label.

validate_address

Checks a US address with carrier address validation, the same check Ship.com runs on orders, and returns a standardized version. It saves nothing, so use it to check an address before you create or update an order. US addresses only.

Returns: is_valid (boolean), standardized (street, street2, city, state, zip) and, only when is_valid is false, a note. When the address is valid, city, state and zip are the validator's standard values: the city is usually uppercase, and the ZIP can come back as ZIP+4 and can differ from the one you sent. When it isn't valid, they echo your input.

Good to know: An address is valid only when there's a single, unambiguous match. Street lines are never corrected. is_valid: false means either that no match exists or that the validation service was briefly unavailable; the result doesn't say which, so retry an address you know is good later. Missing fields are reported together, for example "street is required." or "city, zip are required." To correct an order's saved address, use update_order_address.

{"street": "742 Evergreen Ter", "street2": "Apt 2", "city": "Springfield", "state": "IL", "zip": "62704"}

register_ups

Registers your Ship.com account with UPS, which is required before you can buy UPS labels. It can open a new UPS account or link one you already have. Registering accepts the UPS Technology Agreement, a legally binding contract with UPS Market Driver, Inc. Call it without confirm to get the agreement and a token, show the agreement to the account holder, and confirm with the token only after they explicitly accept it. An AI assistant or integration must never accept on their behalf.

Returns: A preview returns preview: true, registered (whether the account is already registered), note, agreement_version (such as UTA10072022), agreement_token (64 hex characters), prefill (the details that would be sent: company, name, email, phone, street1, city, state, zip, country "US"), missing_fields and, last, agreement_text (the full agreement as plain text, about 71 KB). A confirm returns registered: true, ups_account_last3 (a masked account number such as ***2C3), agreement_version and a note.

Good to know: The token is specific to your account and comes only from a preview. It can change, for example when the agreement is updated, so if a confirm refuses the token, preview again. Contact and address fields are required whether you open or link an account; missing ones are listed in missing_fields, and a confirm without them is refused. Opening a new account sends UPS your company, contact name, email, phone, address and the IP address of the request. There is no charge. Registration can't be undone through MCP, and an account that's already registered is refused (the preview shows registered: true). UPS rows can show up in quote_shipping and get_rates before you register, but buying them fails until you do. US addresses only. UPS-side problems come back as "UPS registration failed: " followed by the reason.

{"confirm": true, "accepted_agreement_token": "<agreement_token from the preview>", "existing_ups_account": "A1B2C3", "existing_ups_postal_code": "30309"}

mark_labels_printed

Marks purchased labels as printed, the same as printing them in the Ship.com web app. Orders move from Label purchased to Label printed, which is what a carrier pickup collects. Call it after buy_label or trigger_batch_purchase, once the labels are actually printed. get_label gives the files: label_url, plus form_url for international orders, whose customs form must be printed too.

Returns: A preview returns preview: true, would_mark_count, would_mark_order_ids, already_printed_order_ids, skipped (each with order_id, status and a reason), free_pickup_order_ids (labels a free pickup will collect once printed), ups_order_ids, outside_pickup_window_order_ids, customs_form_order_ids (labels with a customs form to print too), not_found_order_ids (with order_ids), batch_id and remaining_unprinted_in_batch (with batch_id) and a note. A confirmed call returns marked_count, marked_order_ids, already_printed_order_ids, skipped, failed (each with order_id and a reason), not_found_order_ids, batches_marked_printed, free_pickup_eligible_count, status ("Label printed" when at least one order was marked or was already printed, otherwise null), batch_id and remaining_unprinted_in_batch (with batch_id) and next_step: what to do next, or null. If unprinted labels remain in the batch, it says to finish marking them first: a pickup collects only labels already marked printed, and you can book one free pickup per date. Otherwise, when a free pickup would collect the labels, it suggests schedule_pickup if your plan includes carrier pickup, or dropping them off with the carrier.

Marking a label printed has the same effects as printing it in the web app. Each customer is sent your account's Label Printed tracking email about an hour later, if you have that email turned on. Partner tracking webhooks fire, and so do any automations set to run when a label is printed. That's why it previews first: confirm only after the labels are really printed. For the same reason the tool is annotated destructiveHint: true, so your client may ask before running it. No money moves.

Good to know: Only orders at Label purchased with a label on file change. Orders already at Label printed are listed in already_printed_order_ids and left alone, so repeating a call is safe. Everything else is skipped with a reason and never moved backward: canceled or merged orders, orders with no label bought (including voided labels), and orders past printing, such as Waiting for pickup, In transit or Delivered. UPS labels aren't collected by schedule_pickup; book the paid UPS pickup in the Ship.com web app. A label whose ship date is more than 3 days old, or that's already on a pickup, isn't collected by any carrier pickup, so drop it off instead. The confirmed call checks every order again, so it can differ from the preview. One failed order doesn't stop the rest; call again for the IDs in failed. While a batch's labels are still being bought, both calls return marked_count: 0 and a note to check get_batch_status, and nothing changes. Works on every plan and every connection type. IDs that aren't yours are listed in not_found_order_ids; if none are yours you get None of those orders were found in this account., and an unknown batch returns Batch {batch_id} was not found in this account. Sending both order_ids and batch_id, or neither, returns an error.

{"order_ids": [48213, 48214]}
{"batch_id": 91544, "confirm": true}

check_pickup_availability

Asks the carrier whether it can pick up from your pickup address on a given date. It books nothing and changes nothing in Ship.com. The carrier is chosen the same way schedule_pickup chooses it, from the label-printed packages a pickup would collect. Unlike the schedule_pickup preview, it also returns the carrier's reason when an address isn't eligible.

Returns: available (boolean), pickup_date (YYYY-MM-DD, or null), carrier (USPSDirect or MoveMethod) and error (the carrier's explanation when pickup isn't available, otherwise null).

Good to know: For USPS, the usual carrier, a successful check means your address is eligible for carrier pickup. It doesn't reserve the date: USPS normally returns no date of its own, so pickup_date echoes the date you asked for, and USPS accepts or refuses the date when you book. If USPS does suggest a next eligible date, pickup_date is that date and available is true only when it falls on or before your requested date. An ineligible address or a carrier problem is a normal result, not an error: available: false, pickup_date: null and the carrier's text in error. Ship.com doesn't check for past dates or weekends; the carrier decides. With no label-printed packages waiting, or only UPS ones, it normally checks USPS Direct. Labels that are bought but not marked printed don't count; mark them with mark_labels_printed first. Works on every plan, including plans without carrier pickup. A missing or unreadable date returns date is required, formatted YYYY-MM-DD.

{"date": "2026-10-06"}

schedule_pickup

Books a free carrier pickup at your pickup address. One pickup collects every eligible package at once, and you can't choose a subset. Every collected order moves to Waiting for pickup. UPS-labeled packages are never included; book a paid UPS pickup in the Ship.com web app instead.

A package is eligible when its order is at Label printed, isn't already on a pickup, doesn't have a UPS label, and has a ship date no earlier than 72 hours ago (future ship dates count). Packages on a SCAN form qualify the same way. An order whose label was bought but not yet marked printed stays at Label purchased and isn't collected. The preview lists those labels in unprinted_order_ids and says so in its note; once they're printed, mark them with mark_labels_printed and preview again. There's no limit on how many packages one pickup collects.

Returns: A preview returns preview: true, would_schedule, pickup_date (your requested date), location, carrier, available, eligible_order_count, eligible_order_ids, ups_eligible_count (UPS-labeled packages waiting that this pickup won't collect), already_scheduled_on_date, unprinted_label_count and unprinted_order_ids (bought labels this pickup would collect once they're marked printed) and a note. A confirmed call returns scheduled: true, pickup_id (use it with get_pickup and cancel_pickup), carrier_confirmation (the carrier's confirmation number; rarely null when the carrier returns none, and list_pickups then shows "0"), carrier, pickup_date, order_ids, order_count and status ("Waiting for pickup", the new status of the collected orders).

Good to know: Your plan must include carrier pickup (Growth, Executive or Ultra). The plan is checked first, even for a preview, and otherwise you get Your current Ship.com plan does not include carrier pickup scheduling. Upgrade the subscription to use this tool. Call once without confirm to see what would be collected, then again with confirm: true. The confirmed call re-checks everything at that moment, so its counts can differ from the preview if orders changed in between. would_schedule is true when there are eligible packages and no free pickup on that date yet; it doesn't reflect available, and the preview doesn't include the carrier's reason, so use check_pickup_availability to see why. You can have one free pickup per date; a second is refused until you cancel the first. A paid UPS pickup on the same date doesn't count. One booking runs at a time per account. A second confirmed call waits for the first to finish and then runs its own checks, so a duplicate for the same date is refused. If the first is still running after about 20 seconds, the second returns an error and books nothing. With nothing eligible, the confirmed call returns No orders can be set to pickup. If bought but unprinted labels are waiting, that error also lists their order IDs to mark printed: the first 100, then how many more, since mark_labels_printed takes up to 100 per call. Other errors don't include the list. A carrier refusal, such as an invalid date or characters USPS won't accept, comes back word for word and nothing is booked. To book the visit, the carrier receives your contact details, such as your name, business name, email and phone. Pickups are free: nothing is charged to your postage balance or card, and Ship.com sends no email.

{"date": "2026-10-06", "location": "Front Door", "special_instructions": "Packages on the bench by the garage"}
{"date": "2026-10-06", "location": "Front Door", "special_instructions": "Packages on the bench by the garage", "confirm": true}

cancel_pickup

Cancels a free pickup with the carrier. Every order linked to the pickup goes back to Label printed and is detached from it, so a later pickup can collect it. Paid UPS pickups are refused in both the preview and the confirmed call; cancel those in the Ship.com web app, where the fee is refunded to your postage balance.

Returns: A preview returns preview: true, pickup_id, carrier_confirmation, pickup_date, status (the carrier's status, such as "scheduled" or "canceled"), canceled, linked_order_count (orders currently linked, in any status) and a note. A confirmed call returns canceled: true, pickup_id, carrier (USPSDirect or MoveMethod), reverted_order_ids, reverted_order_count and status ("Label printed", the new status of those orders).

Good to know: Call once without confirm to see the pickup and how many orders would revert, then again with confirm: true. The preview doesn't contact the carrier. Orders change only after the carrier confirms the cancellation; if the carrier refuses, its error comes back and the pickup stays scheduled with nothing changed. Every linked order is set back to Label printed whatever its current status, so cancel only pickups that haven't happened yet. An already-canceled pickup previews normally, with the note "This pickup is already canceled."; confirming it returns Pickup {pickup_id} is already canceled. without contacting the carrier. An ID that doesn't exist or belongs to another account returns Pickup {pickup_id} was not found in this account. Works on every plan. No money moves and Ship.com sends no email.

{"pickup_id": 51874, "confirm": true}

list_pickups

Lists your most recent pickups, newest first, including canceled pickups and paid UPS pickups. Use a row's pickup_id with get_pickup to see its orders, or with cancel_pickup to cancel a free one.

Returns: pickups and count (the rows returned, not an account total). Each row has pickup_id, carrier_confirmation, date (YYYY-MM-DD), status (the carrier's status text), canceled, created, location, special_instructions (as you wrote it, or null), carrier (USPS/MoveMethod for free pickups, UPS for paid ones) and fee_amount (the UPS fee charged to your postage balance; null for free pickups).

Good to know: Rows are ordered by when the pickup was created, not by pickup date. There's no paging, so only your 50 most recent pickups can be reached. The date field is date here but pickup_date in the other pickup tools. created is a UTC time without a zone designator, such as 2026-10-05T18:42:11.523. Rows don't include orders. It reads Ship.com's records only and doesn't contact the carrier. Works on every plan.

{"limit": 5}

get_pickup

Returns one pickup and the orders linked to it. Use it to see which packages a pickup will collect, or to check a pickup before you cancel it with cancel_pickup.

Returns: pickup_id, carrier_confirmation, pickup_date (YYYY-MM-DD), status (the carrier's status text), location, special_instructions, created, canceled, canceled_date (null unless canceled), carrier (USPS/MoveMethod for free pickups, UPS for paid ones), fee_amount (the UPS fee charged to your postage balance; null for free pickups), orders and order_count. orders lists every order linked to the pickup, newest order date first, each with order_id, status (the display label, such as "Waiting for pickup", "In transit" or "Delivered") and tracking_number.

Good to know: A canceled pickup normally shows an empty orders list, because cancelling detaches its orders. created and canceled_date are UTC times without a zone designator. An ID that doesn't exist or belongs to another account returns Pickup {pickup_id} was not found in this account., and a missing ID returns pickup_id is required. It reads Ship.com's records only and doesn't contact the carrier. Works on every plan.

{"pickup_id": 51874}

trigger_batch_purchase

Buys USPS Ground Advantage labels for many ready-to-ship orders at once. Without confirm it rates every eligible order and returns per-order prices and a postage total, buying nothing. With confirm: true it rates the orders again and queues the batch. A background worker then buys one label per rated order, usually within about a minute; follow it with get_batch_status. Bought labels aren't marked printed: once they're printed, call mark_labels_printed with the batch_id so a carrier pickup can collect them.

Returns: A preview returns preview: true, orders, rated_count, failed_count, total_cost (postage for the rated orders), insurance, over_max_total, in_progress_batch (always null) and a note. Each order row has order_id, name, city, state and either rate, method ("USPS Ground Advantage", plus " (Cubic)" or " (Cubic Soft Pack)" when cubic pricing applies) and service_level (such as usps_ground_advantage), or an error explaining why it couldn't be rated, such as a missing weight or an APO/FPO address. Rows are sorted by recipient name. A confirm returns batch_id, requested_count (orders queued), total_cost (postage from the fresh rating), insurance and a note.

Good to know: Available on access-token connections. It is not offered on connections authorized through Ship.com sign-in (OAuth), such as the Claude directory connector and claude.ai custom connectors; there it is absent from tools/list, and a call returns JSON-RPC error -32602 saying the tool is not available. get_batch_status works on every connection. Nothing links a confirm to an earlier preview: confirm rates every order from scratch, so its total can differ, and orders that fail to rate are left out without being listed. If no order can be rated, confirm returns an error and queues nothing. To pin both the orders and the spend, confirm with the same order_ids and a max_total near the previewed total. One batch can be in progress per account, including batches started in the Ship.com web app; until it finishes, preview and confirm return an error that names its batch ID.

Money moves when the worker buys the labels. Each label's postage comes out of your postage balance, and insurance premiums, when on, are charged on top of the postage total and aren't in the preview. With auto-recharge on, if your balance can't cover the batch's postage, your payment method on file is charged once up front for the shortfall or your auto-recharge amount, whichever is larger; if that charge can't be made because there's no payment method or the account is suspended, no labels are bought. If a label fails for a payment reason, the worker stops and marks the remaining orders Not attempted to avoid repeated charges. Each label counts toward your plan's monthly shipment limit, which the preview doesn't check. An order that already has a label isn't bought twice.

Every call, preview included, requests a live USPS rate for each order, so large batches are slow. There is no batch size limit and no service choice. Labels are parcels with no signature, ship-dated when the batch is queued, in your saved label format. Rating, even in a preview, saves the recipient address and weight it used (including a weight_oz fallback) onto each order. Batch rating doesn't run address validation; if an order fails to rate, try get_rates on it alone to see the carrier's reason.

{"order_ids": [48210551, 48210554, 48210560], "max_total": 25.00, "weight_oz": 8}

{"order_ids": [48210551, 48210554, 48210560], "max_total": 25.00, "weight_oz": 8, "confirm": true}

get_batch_status

Reports the progress or result of a batch purchase. Omit batch_id to get the batch in progress, or your most recent batch if none is running. It reads every batch on your account, including batches started in the Ship.com web app, and works on every connection type.

Returns: While labels are being bought: complete: false, batch_id, requested, completed (orders attempted so far, failures included; 0 until the worker starts) and a note. When finished: complete: true, batch_id, orders, purchase_success, purchase_failed, requested, total (postage plus insurance) and shipping_balance (your postage balance). Each order has order_id, name, city, state, shipping_cost (postage plus insurance), tracking_number and status (such as "Label purchased" or "Label printed"), sorted by order date. unprinted_count says how many are bought but not yet marked printed; when it's above 0, next_step tells you to call mark_labels_printed with this batch_id once they're printed. If labels failed, failed_orders lists each order_id with a reason; older batches instead return one combined errors string and a limit_reached flag. A reason is a short code, optionally followed by " - " and detail, for example "Limit reached - 100" when the monthly shipment limit was hit, or "Not attempted - ..." for orders skipped after a payment problem stopped the batch. With no batches, or an unknown batch_id, you get no_status: true and a note as a normal result, not an error.

Good to know: Needs the same plan feature as trigger_batch_purchase, so after moving to a plan without batch shipping you can't read past batches here. orders and purchase_success cover the batch's orders from Label purchased through Delivered, so printed, picked-up and shipped orders stay listed. Orders whose label was voided or that were canceled drop out, as do orders in a return, so purchase_success plus purchase_failed may not equal requested. A batch that stopped before buying anything, for example because the up-front payment couldn't be made, reports complete: true with no orders and no failure detail. A canceled batch also reports complete: true; its voided orders drop out of orders. Rarely, a batch that failed before processing began keeps reporting complete: false; if completed stays at 0 for several minutes, check the orders with list_orders. No label files here: use get_label per order, and get_balance for your current balance.

{"batch_id": 91544}

list_connected_platforms

Lists the sales platforms connected to your account, with each connection's status and last sync time. It reads what Ship.com has stored and doesn't contact the platforms.

No parameters.

Returns: platforms and count. Each platform has name, status, error and last_sync. Only connected platforms appear, in this order and spelled exactly: PayPal, Bomb Party, Shopify, Etsy, Ebay, SquareSpace, Wix, TikTok, WooCommerce, Maverick, Walmart. status is usually Active, Issues or Disconnected, or an empty string if never set. error is a connection error message, currently reported only for Walmart and otherwise null. last_sync is UTC, ISO-8601 without an offset, or null if the store has never synced; WooCommerce shows 0001-01-01T00:00:00 instead of null. With nothing connected: platforms: [], count: 0.

Good to know: One entry per platform, even if you've connected several stores on it. Square, Jotform and spreadsheet or email imports aren't listed. A Shopify store that revoked Ship.com's access can still appear, as Disconnected; reconnect it in Settings → Integrations before syncing. Read last_sync together with status: on a Disconnected Shopify entry it can be the time the problem was found rather than a successful sync.

sync_platform_orders

Starts a background import of recent orders from your connected Shopify or Etsy store and returns right away with a job_id. A sync worker picks the job up, usually within seconds; follow it with get_sync_status. Importing only adds orders Ship.com doesn't already have, so running it again is safe.

Returns: job_id, platform (lowercase), status and a note saying whether a new job was queued or an existing one was returned. status is always queued, even when the returned job is already running.

Good to know: The platform must already be connected in Settings → Integrations; for Shopify the connection must also be active, not uninstalled or revoked. If a sync for that platform is already queued or running, including one started outside MCP such as the import that runs when you first connect a store, that job is returned instead of a second one. Shopify imports orders created in the last 7 days (30 days if the store has never completed a sync), plus new customers from the same window. Etsy imports orders from the last 7 days. Existing Ship.com orders aren't changed and nothing is written back to the store. Newly imported orders can trigger your own automation rules for imported orders and earn rewards points, like any other import. If the store has revoked Ship.com's access, the Shopify connection is marked disconnected or the Etsy connection is removed, and you'll need to reconnect it. No money moves and no email is sent. In the rare case the job can't be queued, you get "Could not queue the sync job"; try again in a moment.

{"platform": "shopify"}

get_sync_status

Checks your background order-import jobs. Pass a job_id from sync_platform_orders to see that one job, or omit it to list your 10 most recent jobs, newest first.

Returns: With job_id, that job's fields directly (no wrapper): job_id, service, platform, status (queued, running, completed or error), queued, started, completed, error and last_sync. Without it, jobs (up to 10 of those objects) and count. Times are UTC, ISO-8601 without an offset; started and completed are null until reached. error is free-text failure detail, or null. For Shopify and Etsy jobs, platform is shopify or etsy and last_sync is the connection's current last sync time, the same on every row for that platform rather than per job. For other jobs, platform repeats the service value and last_sync is null.

Good to know: The list covers all of your account's background import work, not only Shopify and Etsy: spreadsheet uploads, email-forwarded orders, other platforms and tracking refreshes appear too. completed means the job ran, not that orders arrived; an import that ran into a problem can still finish as completed with no error. To confirm orders landed, check that last_sync moved forward and the connection is still Active in list_connected_platforms, or list your orders. A Shopify or Etsy job still running about 10 minutes after it started, or one that hits a temporary failure, is closed with an error and retried as a new job, up to 5 times for stalls. The error text names the new job's ID, so an error row can have a newer follow-up above it. A job is marked completed about 10 seconds after its import finishes.

{"job_id": 73120458}

list_customers

Lists the customers in your Ship.com address book, excluding deleted ones. Filter by name or email and sort alphabetically or by most recent order. Rows are compact; call get_customer for full details and order history. Unlike the email segment tools, this list includes customers who have no email address.

Returns: customers, each with customer_id, name, email, phone, city and state (null when not on file); plus page and page_size as applied, total (matches across all pages) and sort (the sort actually used).

Good to know: A page past the end returns an empty customers list with the real total. Customers that tie in the sort order have no guaranteed order among themselves.

{ "query": "jen", "sort": "recent", "page": 1, "page_size": 10 }

get_customer

Returns the full record for one customer: name, company, contact details, birthday, mailing address, lifetime order count and spend, and their most recent orders.

Returns: customer_id, name, first_name, last_name, company, email, phone, birthday, address (street1, street2, street3, city, state, zip, country), order_count, total_spent and recent_orders. Each recent order has order_id, order_number, date, status (for example "Ready to ship", "Label printed", "In transit", "Delivered"), total and tracking_number.

Good to know: Ship.com stores birthdays as month and day only, so birthday comes back with the year 1900 (for example "1900-04-12T00:00:00"); ignore the year. recent_orders lists up to 20 orders, newest first. order_count, total_spent and recent_orders leave out canceled and merged orders but include orders that haven't shipped yet; the count and total cover every such order, not just the 20 listed. order_number is null when an order has no number, and country is "US" when none is stored. A customer ID that isn't in your account returns an error such as Customer 482913 was not found in this account.

{ "customer_id": 482913 }

create_or_update_customer

Adds a customer to your address book or updates one you already have. Omit customer_id (or pass 0) to create a customer; pass the ID of an existing customer to update them. Changes apply right away, with no confirm step.

Returns: customer_id (new or existing), created (true when a customer was added), name, email, phone, company, birthday, address, orders_updated and note. Values are returned as stored, after the state check, line 2 promotion and country default. orders_updated counts orders changed to match (always 0 on create), and note summarizes them or is null.

Good to know: An update replaces the whole record. Any optional field you leave out is cleared, and country goes back to US. To change one field, read the customer with get_customer first, then send every field back with your change applied.

Every update, even one that doesn't change the name, also updates the customer's orders that don't have a label yet and still carry the name the customer had before the update. Those orders get the customer's new name, company, email, phone and address, so the next label prints the corrected details. Fields you left out are cleared on those orders too, so a partial update can wipe their shipping address. Orders with a purchased, printed or shipped label are never changed, and orders with a different ship-to name are left alone.

Creating a customer doesn't check for duplicates; creating someone who's already in your address book adds a second record. Missing names return first_name and last_name are required., and a customer_id that isn't in your account returns the not-found error described under get_customer.

{
  "customer_id": 482913,
  "first_name": "Jennifer",
  "last_name": "Alvarez-Reyes",
  "email": "jen.alvarez@example.com",
  "phone": "(512) 555-0142",
  "birthday": "04/12",
  "street1": "1208 Maple Ridge Dr",
  "street2": "Apt 4B",
  "city": "Austin",
  "state": "TX",
  "zip": "78704",
  "country": "US"
}

send_customer_email

Sends one marketing email to one of your customers, under your name. Identify the recipient with either customer_id or order_id; the email address comes from that customer or order. The subject and message can use merge placeholders such as {First Name}, filled in for the recipient.

Returns: A preview returns preview (true), recipient_name, recipient_email, subject, limit_check and a note. A confirmed send returns queued (true), recipient (name, email), subject and a note. The subject is echoed as you wrote it, with placeholders not yet filled in. limit_check has allowed, reason, limit, used and message; the last four are null when sending is allowed (see Marketing-email allowance).

Good to know: The preview checks the recipient and your allowance; it doesn't render the email. With "confirm": true, the same checks run again, then the email is queued and goes out about a minute later. Placeholders are filled in when the email is queued. There's no scheduling option on this tool; use send_mass_marketing_email with scheduled_at for timed sends.

A preview isn't required before "confirm": true, and there's no duplicate protection: confirming twice sends two emails. No tool cancels a queued email. Every email includes an unsubscribe link, and addresses that have unsubscribed from Ship.com marketing emails are skipped. If your email settings copy you on emails you send, that applies here too.

Errors include Provide exactly one of customer_id or order_id to identify the recipient., subject and message are required., a not-found error for a customer or order that isn't in your account, and That recipient has no email address on file. If that last one appears for an order whose customer does have an email, send by customer_id instead. When your allowance is used up, the confirm call is refused with the allowance message.

{
  "customer_id": 482913,
  "subject": "A little thank-you, {First Name}",
  "message": "<p>Hi {First Name},</p><p>Thanks for being such a loyal customer! Use code THANKS10 for 10% off your next order.</p><p>{Your Name}</p>",
  "confirm": true
}

send_mass_marketing_email

Sends one marketing email campaign to a segment of your customers, or to your whole emailable list. Filters narrow the audience by purchase history. This sends real email and can't be undone once sending starts, so always preview first and check the recipient count.

Returns: A preview returns preview (true), recipient_count, sample (up to 10 recipients, each with name, email and last_purchase), subject, limit_check and a note. A confirmed send returns queued (true), recipient_count, marketing_email_id (the campaign ID), scheduled_for (UTC) and a note.

Good to know: The audience is the customers in your address book that have an email address, one per address. When several customers share an identical address, the most recently added one is kept; differently capitalized addresses count as different. Customers without an email are never included. Any order counts as a purchase for the filters, including canceled ones.

Always pass filters, days and products as JSON arrays, even for a single filter. A value that isn't an array is ignored, and so is an unrecognized filter string. Ignored filters don't narrow anything, so the campaign could go to your whole list. Check recipient_count in the preview before you confirm.

On confirm, the segment is worked out again, so the count can differ from the preview. The campaign is refused if no one matches or if it would go over your remaining marketing-email allowance; there are no partial sends. The recipient list is fixed when you confirm. Each email goes to the customer's address as it stands at send time, deleted customers are skipped, and each customer gets at most one email per campaign. recipient_count can include addresses that have unsubscribed; they are skipped when sending.

A preview isn't required before "confirm": true, and there's no duplicate protection: confirming twice creates two campaigns. No tool cancels a campaign. Campaigns appear with your other email campaigns in the Ship.com web app. If your email settings copy you on emails you send, you get a copy of every email in the campaign.

{
  "filters": ["has not purchased anything", "has purchased product"],
  "days": [90, 365],
  "products": ["", "lavender"],
  "subject": "We miss you, {First Name}!",
  "message": "<p>Hi {First Name},</p><p>It's been a little while! Our new lavender collection just landed. Take 15% off with code COMEBACK15.</p><p>{Your Name}</p>",
  "scheduled_at": "2026-10-06T15:00:00Z",
  "confirm": true
}

list_lapsed_customers

Finds win-back candidates: customers who haven't ordered in the last N days (60 by default). It sends nothing and doesn't use your marketing-email allowance. Pair it with send_mass_marketing_email or send_customer_email to reach them.

Returns: customers, each with customer_id, name, email and last_purchase (the date of their most recent order of any kind, or null); plus count (rows on this page), total (all matches), page, page_size and days.

Good to know: It uses the same audience rules as send_mass_marketing_email: only customers with an email address, one per address, most recently added customers first. Any order counts as a purchase, including canceled ones. total matches the recipient_count a campaign preview would show for the same segment: ["has not purchased anything"] with days [N], or ["has not purchased product"] with the same days and product. For mail or phone outreach, use list_customers, which includes customers without an email address.

{ "days": 90, "page": 1, "page_size": 25 }

get_balance

Returns your current postage balance and your auto-recharge setting. Check it before buying labels to explain costs and to see whether a purchase would take the balance below zero. With auto-recharge on, that tops the balance up from the payment method on file.

No parameters.

Returns: balance (postage balance in USD; can be negative), currency (USD), auto_recharge_amount (the minimum added each time the balance is topped up), auto_recharge_enabled (true when auto_recharge_amount is more than 0.01) and note, a one-line summary of what the auto-recharge setting means for label purchases.

Good to know: This is the same balance label purchases draw from, so it matches what a purchase will see. When the amount is $0.01 (pay as you go), a shortfall is charged per purchase plus a $0.30 card fee. At $0, auto-recharge is off: the $0.30 fee still applies, and a purchase your balance can't cover fails. auto_recharge_enabled is false in both cases.

get_subscription_info

Returns your plan with its prices, limits and feature flags, plus your recent subscription payments. Call it first to check whether a plan-gated tool will run: business_reporting covers the reporting tools in this section, batch covers batch purchasing and carrier_pickup covers pickup scheduling.

No parameters.

Returns:

• subscription_level: the plan on record, such as starter, growth or executive. Older accounts may show a legacy plan, and it is null when no plan is recorded.
• is_annual: true for annual billing; null when the account has no subscription billing record.
• tier: name, month_price, annual_price (full-year price), month_shipment_limit and month_email_limit (-1 means unlimited), platform_integration_limit, and features, a set of booleans: batch, business_reporting, year_end_reporting, tracking, carrier_pickup, api_access, ai_features, custom_integrations, email_support, priority_email_support, phone_support, chat_support and dedicated_support.
• note: present only when tier is null.
• recent_payments: up to 12 subscription payments, newest first. Each has date, reason, amount_due, amount_paid, refund (0 or a negative amount), charge_id (the payment reference, or unknown), reference_id, status (Succeeded or Pending), failed_reason and note.

Good to know: Legacy plans, and accounts with no plan recorded, return tier: null with a note that per-plan features and limits aren't available; plan-gated tools treat those accounts as not entitled. subscription_level doesn't reflect cancellation, and there is no cancellation field. Only batch, business_reporting and carrier_pickup decide whether MCP tools run; the other flags describe the plan, and api_access and ai_features don't restrict MCP access. Failed charges are left out, and several records for one charge are combined into one entry, with any refunds totaled in refund. On older records status can be null, and entries with charge_id unknown have an empty reference_id. No pagination.

get_referral_info

Returns your referral credit balance and everyone you have referred, including their contact details, plan and what each referral has earned you. To spend the balance on postage, use redeem_referral_credit.

No parameters.

Returns: credit_balance (referral credit in USD), currency (USD) and referrals, one entry per referred account with name, email (may be null), signup_date (when they upgraded, or when they signed up if they haven't upgraded), subscription_level (their plan, such as growth), canceled (true if their account is canceled), has_paid (whether the one-time referral bonus for them has been paid out) and total_payments (referral credit earned from them; 0 if none).

Good to know: referrals lists every account you referred, canceled ones included, in no particular order, with no pagination; it is an empty list if you haven't referred anyone. name can be an empty string when a referred account is missing part of its name.

redeem_referral_credit

Moves your entire referral credit balance into your postage balance so you can spend it on labels. Call it without confirm to preview the two balances, then call again with confirm: true to make the move. It never charges a card or bank account.

Returns: A preview returns preview: true, referral_credit_balance, shipping_balance (your postage balance) and a note. A confirmed call returns redeemed (the amount moved), referral_balance_after (normally 0), shipping_balance_after (your new postage balance) and a note such as "Moved $30.00 of referral credit into the postage balance."

Good to know: It always redeems the whole balance; partial redemption isn't supported. The preview and the confirm aren't linked, so the amount moved is the balance at the moment you confirm, which can differ from the preview. A preview with a $0 balance returns an error that there is nothing to redeem. Rarely, $0 means the balance couldn't be read, so try again later if you expected credit. Confirming at $0 succeeds with redeemed: 0 and moves nothing. The move can't be undone through MCP, and it appears as a referral credit in get_shipping_report. If a confirm reports that the postage balance did not increase, check both balances with get_balance and get_referral_info before trying again, and send one confirm at a time.

{"confirm": true}

get_shipping_report

Returns your shipping spend for one calendar year, broken down by month, plus a year total. It is built from your postage balance activity (label charges, credits and top-ups), not from orders.

Returns: year, months (one entry per month with activity, in calendar order) and total (the whole year). Every entry has these fields:

Good to know: Two keys are camelCase, returnPostage and upsAdjustments, unlike the snake_case used by other tools. postage already has refunds taken out, and the charges in pending are already counted in the charge fields, so don't apply either again. Other balance activity can also affect total, so it may not equal the sum of the named fields. The year's shipments counts each order once, so it can be lower than the sum of the months. A year with no activity returns an empty months list and a total of zeros, with referral and promotional null. Without year the tool returns "year is required."

{"year": 2026}

get_tax_report

Returns the sales tax you collected through paid Ship.com invoices, totaled by quarter and by month, across every year with paid invoices. Useful when filing sales tax.

No parameters.

Returns: taxes, an object whose keys are period labels and whose values are the sales tax collected in USD. Quarter keys look like Q3 2026 and month keys like September 2026. Keys run newest year first; within a year they run from December back to January, with each quarter just before its last month (Q4 2025, December 2025, November 2025, October 2025, Q3 2025, ...). Only periods with paid invoices appear, and taxes is {} when there are none.

Good to know: Tax is counted in the month and quarter the invoice was paid (UTC). Only orders with a paid Ship.com invoice are included, so orders from sales platforms that weren't invoiced through Ship.com aren't. A paid invoice still counts if its order was later canceled. When the current month has paid invoices, its key and every quarter key of the current year end in To Date (for example October 2026 To Date and Q2 2026 To Date); when it has none yet, no key does. Read the period from the start of the key and treat To Date as a label. There are no date filters.

get_shipping_analytics

Returns shipping analytics for a date range in one call: totals, daily order volume, order statuses, carrier mix, top destinations and sales channels. Orders are grouped by the day they were created (UTC). With no dates it covers the last 90 days through today.

Returns:

• start_date, end_date: the range used, YYYY-MM-DD.
• totals: orders (every order created in the range, any status), shipped (orders that currently have a purchased label) and postage_spent (the label prices on those shipped orders).
• daily_volume: {date, orders} per day, oldest first. Days with no orders are left out.
• status_distribution: {status, count}, using the status names from the order statuses table (such as ChooseShipping or Deleted), not the display labels.
• carrier_mix: {carrier, count}. carrier is USPS, MoveMethod (USPS labels bought through a second Ship.com purchasing route; count them as USPS), UPS, unshipped or other (labels that match none of these, such as very old ones).
• top_destinations: up to 10 {state, country, count} entries for the most common ship-to state and country. state is empty when missing, and a blank country reads US.
• sales_channels: {channel, count}, where channel is the order's source as recorded, such as Shopify, Etsy, Square or Jotform. Orders created through the Ship.com REST API show a value starting with API-, orders with no recorded source show manual, and a few may show None.
• truncated and note: present only when the range held more than 100,000 orders. Only the most recent 100,000 were counted; narrow the range for exact numbers.

Statuses, carriers and channels are sorted by count, highest first, with ties in name order; destinations break ties by state.

Good to know: No status filter is applied, so canceled and merged orders count toward every total and breakdown. list_orders, by contrast, filters by status. "Shipped" means the order holds a label right now: voiding a label moves the order back to unshipped. Destinations include unshipped orders, because they use each order's ship-to address. The 366-day limit allows up to 367 calendar days, counting both ends, and the default range spans 91 days. Errors: "end_date must be an ISO date (YYYY-MM-DD).", the same for start_date, "end_date must be on or after start_date." and "The date range is too large — keep it to 366 days or fewer." A future start_date with no end_date fails the on-or-after check.

{"start_date": "2026-07-01", "end_date": "2026-09-30"}