Skip to content

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 type for anything you have not explicitly handled; that is what the coarse class is for.
  • Add a new status value to shipments or bookings. Treat an unknown status as "not terminal, keep polling" rather than crashing.
  • Change the wording of an error message. Branch on code, 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#

GET/api/v1/openapi.jsonNo key needed
Shell
curl https://app.shipeasyco.com/api/v1/openapi.json

An 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_unavailable too. 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:read and bookings:write only. Invoices (list_invoices, get_invoice, get_invoice_pdf) and payment history (list_payments) need payments:read, which an organization's Cards and invoices area grants, and a Shopify store's new Billing area (read only).
  • GET /payment_methods (MCP list_payment_methods) answers a key holding payments:read or bookings:write, so a key that books still names the card it charges. The spec lists both as alternatives in the operation's security. 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.
  • links.tracking on the MCP get_shipment, list_shipments and track_shipment answers is the public page for the shipment's own SHP- 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#

  • origin and destination on a schedule_entry (GET /schedule, MCP list_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:read and payments:write. team:write, developers:write and payments:write are 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 (MCP get_account) gains connection: 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} and POST /catalog/imports (up to 500 models, dry_run first; merge by default, replace only with confirm_replace: true). MCP: list_catalog, get_catalog_item, save_catalog_item, replace_catalog_item, delete_catalog_item, import_catalog. A handling unit on POST /quotes and POST /quotes/bulk may send model_code and quantity instead of its size; the model's boxes are rated. See Catalog.
  • A store's package sizes: /package_sizes list, 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=true lists archived consignees, each consignee gains archived_at, pinned can be written on create and replace (left out, the pin stays), POST /destinations/{id}/restore brings one back, and POST /origins/imports adds up to 200 origins (dry_run first). MCP: restore_destination, import_origins. See Address book.
  • Templates: /templates list, read, save from a quote, rename and delete (writes need addresses:write), and POST /templates/{id}/quote rates 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-status for up to 100 at once, calendar links under /schedule/links, and notes (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, /notifications and /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) and GET /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) and GET /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), and PATCH/DELETE /payment_methods/{id}. A store's GET /payments lists 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_orders and POST /store_orders/quote. MCP: list_stores, import_store_products, disconnect_store, list_store_orders, quote_store_orders. See Stores.
  • Analytics: GET /analytics and GET /analytics/export (CSV). MCP: get_analytics, export_analytics. kpis.in_transit counts freight picked up and moving, and kpis.awaiting_pickup what is booked and not picked up yet. See Analytics.

v1 — 2026-11 · Alliance labels#

  • Alliance shipments can have labels too. has_label on a shipment is now true for an Alliance shipment whose labels Alliance serves, and GET /shipments/{id}/label returns 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 insurance on POST /bookings at 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 same insurance.bind_window.too_short code. GET /account's insurance.bind_cutoff_hour_et is now always 24, 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, as schedule_entry lines: a pickup on its day, a delivery on its day at the delivery dock, and the receiver's preferred days as requested lines that say they are a preference. Scope shipments:read; a Shopify store's key reads it too. The MCP tool is list_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 by status and carrier, and updated_since reads what changed.

v1 — 2026-11 · NA numbers refused for now#

  • A hazmat un_number must be a UN number. An NA number (e.g. NA1993, diesel fuel) is now 400 validation_failed on handling_units[0].hazmat.un_number, code hazmat.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 (MCP get_account) answers it with booking.ready false and one insufficient_scope entry 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[].hazmat on POST /quotes and on each lane of POST /quotes/bulk (and so on the MCP tools quote_freight and quote_freight_bulk) is an optional object: un_number, hazard_class (an enum; classes 1, 6.2 and 7 are refused), packing_group (I, II, III or null), proper_shipping_name and emergency_phone. A bad field is 400 validation_failed on handling_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 answers 422 no_rates_available. See Hazardous materials.
  • POST /bookings takes hazmat_certified (and so does book_quote). It must be true to 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) and White Glove with Assembly, which needs White Glove approval like White Glove. service was 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 /quotes and GET /quotes/{quoteId} gain lane: both ends as rated, in the LaneEnd shape POST /quotes already answers with (city, state, ZIP, residential, and the saved origin's label). It is null on an older quote whose rating didn't keep both ends. MCP's saved-quotes card shows it.
  • …and missing_for_booking, as POST /quotes answers it: what a booking would still need beyond quote_id. It is null when 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 /account and GET /ping gain a shop object, null for an organization's key; organization is null for a store's. booking.billing_mode can be shopify.
  • A shipment's stop fields name and address1 may be null: they always are for a store's key.
  • A store reads, quotes and books its Shopify orders: GET /orders, GET /orders/{orderId} and POST /orders/{orderId}/quote, with the new error code shopify_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 sent destination is ignored.
  • A store's booking.blockers link to its ShipEasy app in Shopify admin, and its booking.payment.mode is shopify: each booking is a charge the store approves in Shopify. POST /bookings/preview is not offered to a store yet (not_available_for_shopify); Shopify's approval page shows the total first.
  • On a store's key, POST /quotes takes origin_id naming one of its ship-from points from GET /origins; destination_id is refused, since a store keeps no saved destinations.
  • On a store's key, an error's fix_url opens 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 answers not_available_for_shopify before any insufficient_scope.
  • Error messages that named "this organization" say "this account", since a store reads them too. No code changed.
  • api_key_expired, api_key_revoked and api_key_mode_mismatch say 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 /account says whether you can book before you quote. booking.ready, booking.blockers (each with the error code a booking would answer and a fix_url to the web app page that fixes it) and booking.payment (mode, default_card, enabled_cards) are new.
  • A card-billed booking may leave out payment when exactly one card is enabled for API bookings; that card is used. With none enabled the booking now answers 402 card_not_enabled_for_api instead of 400 validation_failed; with several, 400 validation_failed on payment.payment_method_id as before.
  • A quote can name saved addresses and carry the destination street. POST /quotes takes origin_id (instead of origin), destination_id (instead of destination_state and destination_postal_code) and a destination object (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, destination and pickup_date are now optional: what is not sent comes from the quote, and whatever is still missing is named per field (destination.phone). pickup_window defaults to the organization's own window instead of full-day. A stop takes contact_name as another word for name.
  • A quote says what it can be booked as. The result gains pickup_date, lane and missing_for_booking; each rate gains bookable and not_bookable_reason. pickup_date is now judged when quoting by the same rule as booking (lead time, weekends, federal holidays) — a bad day is 400 validation_failed naming 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/preview is new (MCP preview_booking): the booking a body would make — stops, day, coverage, payment and total — from the booking's own checks, with ready, issues and blockers. 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, on price_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_quote and request_cancellation ask Claude to confirm on every call; tools that reach a carrier are marked as such. Shipment, booking and tracking links are now pages a person can open — the BOL through the signed-in web app, not the key-only API — and include public tracking.
  • POST /bookings takes expected_amount_usd: the total the person approved. A booking that now totals anything else answers 409 price_changed before anything is charged.

v1 — 2026-11 · coverage terms state the released-value fallback#

  • insurance.terms on GET /account is longer, and insurance.terms_version moved to 2026-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: true on POST /bookings accepts 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 with invalid_redirect_uri.
  • VS Code's https://vscode.dev/redirect is 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/v1 changed.

v1 — 2026-11 · MCP sign-in metadata at the path-suffixed address#

  • /.well-known/oauth-protected-resource/mcp now serves the same protected-resource document as /.well-known/oauth-protected-resource: the address RFC 9728 builds for the /mcp resource, which some MCP clients ask for first. It used to answer 404. See the MCP guide.
  • Nothing in /api/v1 changed.

v1 — 2026-11 · requested delivery days#

  • POST /bookings takes optional requested_delivery_from, requested_delivery_to and requested_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 with validation_failed on that field. The MCP server's book_quote takes them too. See Booking.
  • Nothing was removed or renamed.

v1 — 2026-10 · delivery instructions#

  • POST /bookings takes an optional delivery_instructions (max 200 characters): a note for the delivery driver, printed on the BOL after the delivery service, like origin_instructions is for the pickup. The MCP server's book_quote takes 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", on shipment.alert_opened and wherever a shipment lists its alerts. TAI raises it once an appointment is set, so it was never a request to book one. scheduling now 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_usd and 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 from GET /account now matches what POST /bookings charges.

v1 — 2026-10 · carrier labels#

  • GET /shipments/{id}/label returns the carrier's shipping labels as a PDF, fetched from the carrier when you call. Only AIT shipments have them.
  • has_label on a shipment says whether there is one to fetch, and the MCP server has a matching get_shipment_label tool; get_shipment's links gain label_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/v1 changed.

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_unavailable with Retry-After. No carrier is asked, and no quote is saved or listed. This holds for POST /quotes/bulk as a whole: it answers 503, not a 200 with an error on each lane, and its Idempotency-Key is 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 /account usage.degraded is true when the counters cannot be read in time. requests still counts this call; quotes and bookings then 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 with 403 insufficient_scope. A trailing slash is now ignored on the URL, as it already was on resource.
  • 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/v1 changed.

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 S256 only, and revocation (RFC 7009).
  • A /mcp request with no token gets a 401 whose WWW-Authenticate names resource_metadata.
  • Each connection is listed on the API keys page under Connected AI apps, where Disconnect ends it.
  • Nothing in /api/v1 changed, and a pasted key works at /mcp as 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.