Changelog & versioning
Contents 26 pages
The version#
The API is versioned in the path: /api/v1. There is no version header and no
date-pinning. One version is live, and it is v1.
What we will not do to v1#
These are breaking:
- Remove or rename a field in a response.
- Remove an endpoint, or change what an existing HTTP method on a path does.
- Add a required request field, or make an optional one required.
- Narrow an accepted value — tightening a length limit, dropping an enum member.
- Change a field's type, including "3" becoming 3.
- Change an HTTP status for an outcome you already handle.
- Repurpose an error code to mean something else.
We do not ship them into v1, except to fix a bug: where the server disagreed
with this reference, or did something it could not stand behind. Each of those
is listed under Releases with what to change.
Any other change of this kind goes in /api/v2, and v1 keeps working for
at least twelve months after v2 ships. We will email every organization
with an active API key before that clock starts, and again before it runs out.
What we will do without warning#
These are additive, and your client must tolerate them:
- Add a field to a response. Parse leniently — ignore what you do not recognise rather than failing on it.
- Add a new endpoint.
- Add an optional request field, or a new accepted enum value.
- Add a new error code. Branch on
typefor anything you have not explicitly handled; that is what the coarse class is for. - Add a new
statusvalue to shipments or bookings. Treat an unknown status as "not terminal, keep polling" rather than crashing. - Change the wording of an error
message. Branch oncode, never on prose. - Change rate limits and quotas. Read them from the headers and
GET /account, not from a constant in your code.
Two rules make a client survive all of the above: branch on code, not
message, and ignore unknown fields.
OpenAPI#
/api/v1/openapi.jsonNo key neededcurl https://app.shipeasyco.com/api/v1/openapi.jsonAn OpenAPI 3.1 document describing every endpoint, its parameters, its request body and its responses. Public — no key required, because you need it before you have one.
It carries an ETag; send If-None-Match and you will get a 304 when nothing
has changed.
The document is written by hand beside the routes, and tests in our build hold it to them. They fail if an endpoint exists without appearing in the spec, or the spec describes a path that does not exist; if a list endpoint reads a query parameter the spec does not list, or the reverse; if a quote, bulk-quote, booking, origin or destination request reads a body field the spec does not list, or the reverse; and if an operation names a scope its route does not enforce.
Use it to generate a client, or point Postman or Insomnia at it.
Releases#
v1 as these pages describe it is the first release. Changes from here on are
listed here, newest first.
v1 — 2026-11-20 · with AI writes off, AI apps only read and quote#
- While ShipEasy has the MCP tools that change something switched off (an
incident switch), an AI app is offered only the tools that read or quote,
as the switch has always been described. Until now the catalog, support,
settings and store tools that write stayed on; they are now hidden and answer
api_unavailabletoo. Quoting (quote_freight,quote_freight_bulk,quote_from_template,rate_shipment_again,quote_order,quote_store_orders) stays on. The REST API is untouched. - Meanwhile the AI sign-in page offers no area that changes anything, and changing a connected app's areas keeps the ones it holds but cannot be offered right now, where it used to drop them.
v1 — 2026-11-20 · booking is not billing#
- "Book shipments" no longer reads invoices and payments. An AI app's
Book shipments area, the Quote, track and book and Quote, track,
book and manage levels, and the For an AI agent that books key preset
now grant
bookings:readandbookings:writeonly. Invoices (list_invoices,get_invoice,get_invoice_pdf) and payment history (list_payments) needpayments:read, which an organization's Cards and invoices area grants, and a Shopify store's new Billing area (read only). GET /payment_methods(MCPlist_payment_methods) answers a key holdingpayments:readorbookings:write, so a key that books still names the card it charges. The spec lists both as alternatives in the operation'ssecurity. Additive: every key that could call it still can.- Existing connections. An AI app connected with Book shipments (or a
booking level) and not Cards and invoices loses
payments:read: it can no longer list invoices or payments, and still books and lists the cards it may charge. To widen it, an owner or admin ticks Cards and invoices on the app's card under AI & API (a store ticks Billing in its ShipEasy app), which applies to the app's next request. API keys a person made keep the scopes they were given.
v1 — 2026-11 · MCP tracking links by reference#
links.trackingon the MCPget_shipment,list_shipmentsandtrack_shipmentanswers is the public page for the shipment's ownSHP-reference, as every ShipEasy email and the web app share it, and the PRO only for a shipment with no reference. A PRO is not unique across carriers, so the old link could open another shipment. No field or type changed.
v1 — 2026-11 · a weight is read whole#
A bug fix. weight_lbs, length_in, width_in and height_in on a
handling unit (POST /quotes, POST /quotes/bulk, MCP quote_freight) are
read as the whole value: "1,200" is 1,200 lb, where it was rated as 1 lb. A
string with anything after the number ("48in", "300 lbs") is now
400 validation_failed on that field, where its leading digits were rated, and
so is an exponent ("1e3").
Send digits with an optional decimal point. See
Handling units.
v1 — 2026-11 · schedule places in title case#
originanddestinationon aschedule_entry(GET /schedule, MCPlist_schedule) print the city in title case,Dallas, TX, where a carrier sent it in capitals (DALLAS, TX), as every other ShipEasy surface prints it. A city known without its state reads as the city alone, never its ZIP. No field or type changed. See Pickups and deliveries by day.
v1 — 2026-11 · everything the web app does#
Every page and action of the web app and the Shopify app now has an operation,
and so an MCP tool. They answer 404 unknown_endpoint, and AI apps are not
offered them, until ShipEasy turns them on for everyone; this entry describes
them once they are on. All of it is additive.
- New scopes:
catalog:read,catalog:write,support:read,support:write,documents:read,settings:read,settings:write,team:read,team:write,developers:read,developers:write,analytics:readandpayments:write.team:write,developers:writeandpayments:writeare sensitive: only an owner or admin grants them. A key you already hold keeps exactly its scopes. See Scopes. - AI apps are let in area by area. The sign-in page lists what an AI app may
do as checkboxes (catalog, support, settings, team, API keys and webhooks,
cards and invoices, and the rest), and a connection's areas can be changed on
ShipEasy's AI page without connecting again.
GET /account(MCPget_account) gainsconnection: the areas the key or connection holds, the ones it lacks, and where a person changes them. ChatGPT is never offered booking or cards and invoices. See What an AI app may do. - Catalog:
GET/POST /catalog,GET/PATCH/DELETE /catalog/{modelId}andPOST /catalog/imports(up to 500 models,dry_runfirst;mergeby default,replaceonly withconfirm_replace: true). MCP:list_catalog,get_catalog_item,save_catalog_item,replace_catalog_item,delete_catalog_item,import_catalog. A handling unit onPOST /quotesandPOST /quotes/bulkmay sendmodel_codeandquantityinstead of its size; the model's boxes are rated. See Catalog. - A store's package sizes:
/package_sizeslist, read, add, replace, delete, restore and import, for a Shopify store's key. MCP:list_package_sizes,get_package_size,save_package_size,replace_package_size,delete_package_size,restore_package_size,import_package_sizes. See Package sizes. - Address book:
GET /destinations?archived=truelists archived consignees, each consignee gainsarchived_at,pinnedcan be written on create and replace (left out, the pin stays),POST /destinations/{id}/restorebrings one back, andPOST /origins/importsadds up to 200 origins (dry_runfirst). MCP:restore_destination,import_origins. See Address book. - Templates:
/templateslist, read, save from a quote, rename and delete (writes needaddresses:write), andPOST /templates/{id}/quoterates one now. MCP:list_templates,get_template,save_template,rename_template,delete_template,quote_from_template. See Templates. - Shipments:
POST /shipments/{id}/ship-again,GET /shipments/report,GET /shipments/export(CSV),POST /shipments/refresh-statusfor up to 100 at once, calendar links under/schedule/links, andnotes(what ShipEasy's team wrote for you) on a shipment. MCP:rate_shipment_again,get_status_report,export_shipments,refresh_shipments,list_calendar_links,create_calendar_link,revoke_calendar_link. See Shipments. - Support and documents:
/support/cases(list, read, open, reply),POST /feedback,POST /white_glove_requests,/notificationsand/documents. MCP:list_support_cases,get_support_case,open_support_case,reply_support_case,send_feedback,request_white_glove,list_notifications,mark_notifications_read,list_documents,get_document. See Support and Documents. - Settings:
GET/PATCH /settings(only the fields sent change), text alerts under/settings/text_alerts, branding under/branding(logo, reply-to, tracking domain, test email) andGET /referrals. MCP:get_settings,update_settings,set_up_text_alerts,confirm_text_alerts,remove_text_alerts,get_branding,update_branding,set_brand_logo,remove_brand_logo,send_brand_test_email,set_reply_to_email,remove_reply_to_email,set_tracking_domain,check_tracking_domain,remove_tracking_domain,get_referrals. See Settings. - Team (organizations):
GET /members,POST /invitations,DELETE /invitations/{id},PATCH/DELETE /members/{id}. Never the owner, never the person behind the key. MCP:list_members,invite_member,revoke_invitation,update_member,remove_member. See Team. - Keys, webhooks, AI apps and usage:
/api_keys(list, create with no more than the calling key holds, rotate, revoke; a key never ends itself),/webhook_endpoints(list, add, change events, rotate the secret, test, remove),/ai_connections(list, disconnect) andGET /usage(7 or 30 days of usage and refusals). A secret is answered once. MCP:list_api_keys,create_api_key,rotate_api_key,revoke_api_key,list_webhook_endpoints,add_webhook_endpoint,update_webhook_endpoint,rotate_webhook_secret,send_webhook_test,remove_webhook_endpoint,list_ai_connections,disconnect_ai_connection,get_usage. See Developer settings. - Cards, invoices and payments (organizations):
/invoices(list, read, PDF),POST /invoices/{id}/pay(a Stripe payment page to open; nothing is charged by the call),GET /payments,GET /payment_methods/setup(the page where a person adds a card), andPATCH/DELETE /payment_methods/{id}. A store'sGET /paymentslists its Shopify charges. MCP:list_invoices,get_invoice,get_invoice_pdf,pay_invoice,list_payments,get_card_setup_link,update_payment_method,remove_payment_method. See Billing. - Connected stores (organizations):
GET /stores,POST /stores/{id}/product_imports,DELETE /stores/{id},GET /store_ordersandPOST /store_orders/quote. MCP:list_stores,import_store_products,disconnect_store,list_store_orders,quote_store_orders. See Stores. - Analytics:
GET /analyticsandGET /analytics/export(CSV). MCP:get_analytics,export_analytics.kpis.in_transitcounts freight picked up and moving, andkpis.awaiting_pickupwhat is booked and not picked up yet. See Analytics.
v1 — 2026-11 · Alliance labels#
- Alliance shipments can have labels too.
has_labelon a shipment is nowtruefor an Alliance shipment whose labels Alliance serves, andGET /shipments/{id}/labelreturns them, as it does for AIT. No field changed. See Labels.
v1 — 2026-11 · coverage for a pickup today, at any hour#
- Coverage is no longer cut off before pickup. A pickup today or tomorrow can
take
insuranceonPOST /bookingsat any hour; before, a same-day pickup was refused and a next-business-day one only before 2 PM US Eastern. Only a pickup date that has passed is refused, with the sameinsurance.bind_window.too_shortcode.GET /account'sinsurance.bind_cutoff_hour_etis now always24, an integer as before, so nothing that reads it breaks. See Booking.
v1 — 2026-11 · pickups and deliveries by day#
GET /schedule?from=&to=lists pickups and deliveries by day, at most 62 days, asschedule_entrylines: a pickup on its day, a delivery on its day at the delivery dock, and the receiver's preferred days asrequestedlines that say they are a preference. Scopeshipments:read; a Shopify store's key reads it too. The MCP tool islist_schedule. See Pickups and deliveries by day.list_shipments' description no longer says it filters by reference or date, which it never did: it filters bystatusandcarrier, andupdated_sincereads what changed.
v1 — 2026-11 · NA numbers refused for now#
- A hazmat
un_numbermust be a UN number. AnNAnumber (e.g.NA1993, diesel fuel) is now400 validation_failedonhandling_units[0].hazmat.un_number, codehazmat.naNumber, because the carrier's bill of lading cannot print one correctly yet. UN numbers are unchanged. See Hazardous materials.
v1 — 2026-11 · ChatGPT quotes and tracks#
- A ChatGPT connection never books from the chat. Its sign-in offers
Quote and track only, and
GET /account(MCPget_account) answers it withbooking.readyfalse and oneinsufficient_scopeentry saying booking happens on ShipEasy. Other keys and connections are unchanged. See ChatGPT.
v1 — 2026-11 · hazardous materials, and two new services#
- A handling unit can declare hazardous materials.
handling_units[].hazmatonPOST /quotesand on each lane ofPOST /quotes/bulk(and so on the MCP toolsquote_freightandquote_freight_bulk) is an optional object:un_number,hazard_class(an enum; classes 1, 6.2 and 7 are refused),packing_group(I,II,IIIornull),proper_shipping_nameandemergency_phone. A bad field is400 validation_failedonhandling_units[0].hazmat.<field>. Only a carrier with a hazmat rate quotes a declared lane (today CEVA, with its Hazardous Materials charge in the price); when none does, the lane answers422 no_rates_available. See Hazardous materials. POST /bookingstakeshazmat_certified(and so doesbook_quote). It must betrueto book a quote that declares hazmat, and is ignored otherwise. See Booking.- Rates can name two more services:
No Signature Required(left outside, no appointment,appointment_required: false) andWhite Glove with Assembly, which needs White Glove approval likeWhite Glove.servicewas always a string; branch on it leniently. - Nothing is required of a request that declares no hazmat.
v1 — 2026-11 · a saved quote names its lane and what booking it needs#
GET /quotesandGET /quotes/{quoteId}gainlane: both ends as rated, in theLaneEndshapePOST /quotesalready answers with (city, state, ZIP, residential, and the saved origin'slabel). It isnullon an older quote whose rating didn't keep both ends. MCP's saved-quotes card shows it.- …and
missing_for_booking, asPOST /quotesanswers it: what a booking would still need beyondquote_id. It isnullwhen the quote's request can't be read back.
v1 — 2026-11 · Shopify stores#
- A Shopify store can hold API keys and connect AI apps. Its key reaches the store's own quotes and shipments, with stops as city, state, ZIP and country only. See Shopify stores.
- New error code
not_available_for_shopify(403), for the operations a store's key may not use. GET /accountandGET /pinggain ashopobject, null for an organization's key;organizationis null for a store's.booking.billing_modecan beshopify.- A shipment's stop fields
nameandaddress1may be null: they always are for a store's key. - A store reads, quotes and books its Shopify orders:
GET /orders,GET /orders/{orderId}andPOST /orders/{orderId}/quote, with the new error codeshopify_stores_only(403) for an organization's key. - A store's booking fills from its quote, as an organization's does. For a
quote made with
POST /orders/{orderId}/quote, the destination is the order's own ship-to, read when it books; a sentdestinationis ignored. - A store's
booking.blockerslink to its ShipEasy app in Shopify admin, and itsbooking.payment.modeisshopify: each booking is a charge the store approves in Shopify.POST /bookings/previewis not offered to a store yet (not_available_for_shopify); Shopify's approval page shows the total first. - On a store's key,
POST /quotestakesorigin_idnaming one of its ship-from points fromGET /origins;destination_idis refused, since a store keeps no saved destinations. - On a store's key, an error's
fix_urlopens its ShipEasy app in Shopify admin, and is left out where the store has nothing to fix there. A missing scope links to AI & API in the app (/app/ai), where the store makes its keys. An endpoint a store's key may not use answersnot_available_for_shopifybefore anyinsufficient_scope. - Error messages that named "this organization" say "this account", since a store reads them too. No code changed.
api_key_expired,api_key_revokedandapi_key_mode_mismatchsay what to do for the key they refuse. A key points at where its owner makes keys: AI & API in the web app, or in the ShipEasy app in Shopify admin. An AI app's connection is told its token renews on its own, or that it was disconnected, never to make a key. No code or status changed.- An organization's key is unchanged.
v1 — 2026-11 · booking made easier for AI apps#
GET /accountsays whether you can book before you quote.booking.ready,booking.blockers(each with the errorcodea booking would answer and afix_urlto the web app page that fixes it) andbooking.payment(mode,default_card,enabled_cards) are new.- A card-billed booking may leave out
paymentwhen exactly one card is enabled for API bookings; that card is used. With none enabled the booking now answers402 card_not_enabled_for_apiinstead of400 validation_failed; with several,400 validation_failedonpayment.payment_method_idas before. - A quote can name saved addresses and carry the destination street.
POST /quotestakesorigin_id(instead oforigin),destination_id(instead ofdestination_stateanddestination_postal_code) and adestinationobject (contact, street, phone). A sent destination street is remembered in the address book, as the web app does. - A booking fills from its quote. On
POST /bookings,origin,destinationandpickup_dateare now optional: what is not sent comes from the quote, and whatever is still missing is named per field (destination.phone).pickup_windowdefaults to the organization's own window instead offull-day. A stop takescontact_nameas another word forname. - A quote says what it can be booked as. The result gains
pickup_date,laneandmissing_for_booking; each rate gainsbookableandnot_bookable_reason.pickup_dateis now judged when quoting by the same rule as booking (lead time, weekends, federal holidays) — a bad day is400 validation_failednaming the earliest that works — and an omitted one rates the earliest allowed day, as the reference always said. Before, it was rated for no particular day and the booking was not held to one. POST /bookings/previewis new (MCPpreview_booking): the booking a body would make — stops, day, coverage, payment and total — from the booking's own checks, withready,issuesandblockers. It charges, books and re-rates nothing.- Errors say how to fix them. The error object gains
fix_url— an absolute link to the web app page that fixes the refusal, where a person can — and, onprice_changed,new_amount_usd. - The MCP server speaks to an agent. Tool and argument words name tools
instead of endpoints, each tool says what it is for, and the server gives a
short booking playbook. It offers three prompts (
ship_freight,track_shipments,compare_carriers).book_quoteandrequest_cancellationask Claude to confirm on every call; tools that reach a carrier are marked as such. Shipment, booking and trackinglinksare now pages a person can open — the BOL through the signed-in web app, not the key-only API — and include public tracking. POST /bookingstakesexpected_amount_usd: the total the person approved. A booking that now totals anything else answers409 price_changedbefore anything is charged.
v1 — 2026-11 · coverage terms state the released-value fallback#
insurance.termsonGET /accountis longer, andinsurance.terms_versionmoved to2026-11-06-a. The coverage conditions now also say that until a certificate is issued only the carrier's released value covers the shipment, and that the premium is refunded if none is issued.accept_terms: trueonPOST /bookingsaccepts that text. See Booking.- No field, status or error code changed.
v1 — 2026-11 · Cursor and VS Code sign in to MCP#
- Cursor can register and sign in. Dynamic client registration accepts
Cursor's own
cursor://anysphere.cursor-mcp/…redirect. Every other non-web redirect is still refused withinvalid_redirect_uri. - VS Code's
https://vscode.dev/redirectis a known host, so a bad sign-in request from it comes back as?error=like Claude's and ChatGPT's. See the MCP guide. - Nothing in
/api/v1changed.
v1 — 2026-11 · MCP sign-in metadata at the path-suffixed address#
/.well-known/oauth-protected-resource/mcpnow serves the same protected-resource document as/.well-known/oauth-protected-resource: the address RFC 9728 builds for the/mcpresource, which some MCP clients ask for first. It used to answer 404. See the MCP guide.- Nothing in
/api/v1changed.
v1 — 2026-11 · requested delivery days#
POST /bookingstakes optionalrequested_delivery_from,requested_delivery_toandrequested_delivery_note: the days the receiver can take delivery, and the times that work. We tell the carrier, which books the appointment; it is a preference, not a guaranteed date. A day the freight cannot reach (before pickup plus the quote's transit) or more than 15 business days past that is refused withvalidation_failedon that field. The MCP server'sbook_quotetakes them too. See Booking.- Nothing was removed or renamed.
v1 — 2026-10 · delivery instructions#
POST /bookingstakes an optionaldelivery_instructions(max 200 characters): a note for the delivery driver, printed on the BOL after the delivery service, likeorigin_instructionsis for the pickup. The MCP server'sbook_quotetakes it too. See Booking.- Nothing was removed or renamed.
v1 — 2026-10 · "Appointment Date" is progress#
- The TAI alert "Appointment Date" now arrives with
category: "progress", not"scheduling", onshipment.alert_openedand wherever a shipment lists its alerts. TAI raises it once an appointment is set, so it was never a request to book one.schedulingnow means only "Delivery Appointment Requested" and "Pickup Appointment Requested". Nothing changed shape.
v1 — 2026-10 · the coverage premium is exactly the published terms#
- A booking's coverage premium is now the larger of
minimum_premium_usdand declared value ×rate_per_100_usd/ 100, to the cent, as Booking states. It was priced from our cost and marked up afterwards, which could differ from that by a cent or two. Nothing on the wire changed shape; a premium you compute fromGET /accountnow matches whatPOST /bookingscharges.
v1 — 2026-10 · carrier labels#
GET /shipments/{id}/labelreturns the carrier's shipping labels as a PDF, fetched from the carrier when you call. Only AIT shipments have them.has_labelon a shipment says whether there is one to fetch, and the MCP server has a matchingget_shipment_labeltool;get_shipment'slinksgainlabel_pdf.- No field was removed or renamed. See Shipments and tracking.
v1 — 2026-10 · signing out everywhere disconnects AI apps#
- An AI app connection ends with its person's sessions. When the person who
connected it signs out everywhere, changes or resets their password, changes
their sign-in email or deletes their account, or ShipEasy disables the
account, the connection is disconnected at once, as Disconnect does it.
Leaving an organization, or being removed from it, ends that organization's
connections.
Its access token stops working and its refresh token is refused with
invalid_grant. - A refresh refuses a connection allowed before such a cutoff, with
invalid_grant, and ends it. Connect again through/oauth/authorize. See the MCP guide. - Ordinary API keys are not affected. Nothing in
/api/v1changed.
v1 — 2026-10 · quotes are counted before they are rated#
- A call that cannot be counted is refused, and nothing runs. If the usage
counters cannot answer in time, the call gets
503 api_unavailablewithRetry-After. No carrier is asked, and no quote is saved or listed. This holds forPOST /quotes/bulkas a whole: it answers 503, not a 200 with an error on each lane, and itsIdempotency-Keyis released, so a retry with the same key can succeed. - Lanes are counted before carriers are asked. A lane that comes back with no rate is handed back to your daily budget. Lanes past what is left of the budget are not rated.
GET /accountusage.degradedistruewhen the counters cannot be read in time.requestsstill counts this call;quotesandbookingsthen read 0 used.- No field was removed or renamed. See Rate limits.
v1 — 2026-10 · /mcp/ works, and sign-in errors reach only known connectors#
- A connector set to
https://app.shipeasyco.com/mcp/works. It could sign in, then every call was refused with403 insufficient_scope. A trailing slash is now ignored on the URL, as it already was onresource. - A bad sign-in request goes back only to a host ShipEasy knows. For a
redirect on claude.ai, claude.com, chatgpt.com, chat.openai.com or your own
computer, a problem in the request still comes back to the client as
?error=. For any other host the person now sees the problem on ShipEasy's page and is sent nowhere. If you build a connector on your own domain, look for these errors there, not at your callback. See the MCP guide. - Nothing in
/api/v1changed.
v1 — 2026-10 · two refreshes close together no longer end a connection#
A refresh token used after it was rotated ended the connection, so a connector
that sent two refreshes close together lost it on the second, and the person had
to connect again. The token replaced in the last 60 seconds is now refused with
invalid_grant and the connection stays: use the refresh token from the first
answer. An older token coming back still ends the connection.
v1 — 2026-10 · claude.ai, Claude Desktop and ChatGPT connect by signing in#
Apps that cannot take a pasted key can now reach /mcp by signing in with
OAuth. A person adds https://app.shipeasyco.com/mcp as a custom connector, and
an owner or admin allows it in the web app, choosing the organization and what
the app may do: quote and track, also book, or also book and manage. The
MCP guide has the steps, and what a client author needs.
- The access token is an API key that lasts an hour, works only at
/mcp, and is refused by the REST API. A refresh token renews it and rotates on every use. - The server offers discovery (RFC 9728, RFC 8414), dynamic client
registration (RFC 7591), the authorization code flow with PKCE
S256only, and revocation (RFC 7009). - A
/mcprequest with no token gets a 401 whoseWWW-Authenticatenamesresource_metadata. - Each connection is listed on the API keys page under Connected AI apps, where Disconnect ends it.
- Nothing in
/api/v1changed, and a pasted key works at/mcpas before.
Subscribing to changes#
There is no changelog feed yet. Until there is, the honest answer is: we email the address on your API key, and the address on your organization, before anything breaking. Keep at least one of them monitored by more than one person.