Shopify stores
Contents 26 pages
A store that ships with ShipEasy's Shopify app can use the same API and the same MCP server as a web app organization. Its keys and AI app connections belong to the store, and they reach the store's own quotes and shipments.
Connect an AI app or make a key#
In the ShipEasy app inside Shopify admin, open AI & API in the app's menu. That page has the MCP address, the steps for each AI app, the apps the store has connected, and API keys for the store's own code.
An AI app signs in without a key. On ShipEasy's sign-in page, choose Use ShipEasy in Shopify? Connect your store instead and enter the store's address. ShipEasy opens inside Shopify admin, where a staff member of the store picks what the app may do and presses Allow:
| Level | What the app may do |
|---|---|
| Quote and track | Read the account, rate freight, follow quotes and shipments. |
| Quote, track and book | Also book a rate. Every booking is a Shopify charge the store approves (see below). |
| Quote, track, book and manage | Also refresh tracking and ask for a cancellation. |
While ShipEasy's newer areas are on, the staff member ticks areas instead: Quote and track is always included (it also reads package sizes, support cases, settings and analytics), then Book shipments, Refresh and cancel shipments, Saved shipments, Package sizes, Support cases and requests, Settings and branding, API keys and Billing (reads what ShipEasy charged the store; booking does not). A store is never offered an address book, team, or cards and invoices. Staff can change a connected app's areas later under AI & API, without connecting again (see what an AI app may do).
ChatGPT is offered Quote and track only, because OpenAI allows no booking or payment inside ChatGPT: the store books in its ShipEasy app in Shopify admin (see ChatGPT).
A store's key and connections stop working when the store uninstalls the app.
Under AI & API → Usage & problems, the store sees what its AI apps and keys used against its daily limits, day by day, and every refusal they got, in plain words (refusals you can see).
What a store's key sees#
A shipment comes back with the city, state, ZIP and country of each stop, and
never a buyer's name, company, phone, email or street. Those fields are
null. Tracking events carry dates, ids and codes; an alert's free-text reason
is left out.
These operations answer 403 not_available_for_shopify,
and an AI app is not offered them:
GET /shipments/{id}/bol,/podand/label. The documents print the buyer's name and street; open the shipment in the Shopify app instead.get_shipmentlinks there aslinks.shopify_admin.GET,POST,PATCHandDELETEon/destinations. The store's ship-to book holds its buyers' details.POST,PATCHandDELETEon/origins. A store's ship-from points live in Shopify.GET /originslists its Shopify locations and its saved warehouse, with ids likeloc_123ormanual.GET /payment_methods, every/invoicesoperation, and/payment_methods/setupand/payment_methods/{id}. A store pays through Shopify, not by card or invoice;GET /paymentslists its Shopify charges (Invoices, payments & cards).- Every
/catalogoperation. The catalog is the web app's; a store's package sizes live with its Shopify products and have their own operations,/package_sizes, which only a store's key reaches. A quote'smodel_codeis refused at that unit for the same reason. GET /shipments/export. The web app's shipments CSV; a store reads its shipments withGET /shipments.GET /documentsand/documents/{id}. Library paperwork can print the buyer's name; open it in the Shopify app instead.- Every
/membersand/invitationsoperation. A store's staff live in Shopify. - Every
/storesand/store_ordersoperation. Those are a web app organization's connected stores; a store reads its own Shopify orders withGET /orders. - Every
/webhook_endpointsoperation, andPOST /api_keys/{id}/rotate. Webhooks are the web app's; a store makes a new key and revokes the old one.
That refusal comes first, before any insufficient_scope: a new key would not
help. An error's fix_url opens the page in the ShipEasy app inside Shopify
admin where the store fixes it, and is left out where there is none there.
GET /account names the store under shop and leaves organization null.
A store reads and changes its templates, rates a past
shipment again, reads the status report (with every note left out) and keeps
its calendar subscribe links
and its notices.
Its support cases work as an organization's. A shipment's notes are always empty for a
store, since a note may name the buyer.
Orders#
A store's key reads the store's own Shopify orders, live from Shopify and
place-only: the order's facts, its items and the ship-to city, state, ZIP and
country — never the buyer's name, company, street, phone or email. These
endpoints answer shopify_stores_only
to an organization's key. Reading needs shipments:read; quoting needs
quotes:write.
/api/v1/ordersScope shipments:readNewest first. status is unfulfilled (the default) or all; limit and
starting_after page as everywhere else, and next_cursor is passed back
verbatim. Each order says whether it is ready_to_quote: every item has a saved
box size. The units those sizes make are in handling_units, and items still
missing one are named in unsized_items — the merchant saves them in the
ShipEasy app under Package dimensions.
curl "https://app.shipeasyco.com/api/v1/orders?status=unfulfilled" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"/api/v1/orders/{orderId}Scope shipments:readOne order by Shopify's numeric id, in the same shape.
/api/v1/orders/{orderId}/quoteScope quotes:writeRates the order as it stands: its saved box sizes, the store's default
ship-from (or origin_id from GET /origins) and the order's ship-to. An order
naming a company is a business delivery, otherwise the store's usual delivery
type; destination_residential overrides it. pickup_date and
include_all_carriers work as on POST /quotes. An order missing a box size
answers validation_failed, naming the items.
curl https://app.shipeasyco.com/api/v1/orders/5523011239/quote \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pickup_date": "2026-11-20"}'{
"object": "quote_result",
"order_id": "5523011239",
"pickup_date": "2026-11-19",
"missing_for_booking": [],
"rates": [
{
"object": "rate",
"quote_id": "cm2k8r9f2…",
"carrier": "Alliance Air Freight",
"carrier_scac": "ANCF",
"service": "Curbside Delivery",
"description": "Liftgate + delivery to entrance or receiving area.",
"amount_usd": "419.00",
"currency": "USD",
"transit_days": 4,
"appointment_required": true,
"expires_at": "2026-11-19T20:14:49.208Z",
"cheapest_for_service": true,
"bookable": true,
"not_bookable_reason": null
}
]
}pickup_date is the day the rates are for: the one sent, judged by the store's
lead time, or else the earliest allowed. missing_for_booking lists what a
booking still needs, such as origin.phone; it never lists a destination field.
Book a rate with POST /bookings and its quote_id. For an order's quote the
ship-to is the order's own, read from Shopify at booking and never returned, so
leave destination out (one sent is ignored). If the order's ship-to lacks a
street or a phone, the booking names the field; add it to the order in Shopify.
An order's quote cannot declare hazardous materials, since it rates the order's
saved boxes. To ship hazmat, quote with POST /quotes and
handling_units[].hazmat, and book with hazmat_certified: true, as an
organization does.
origin may be left out too, to collect from the ship-from the order was rated
from. Once the store approves the charge, the shipment is the order's: Shopify
marks it fulfilled at pickup, as for a booking made in the Shopify app.
Quoting#
POST /quotes and POST /quotes/bulk work as for an organization, with the
carriers the store has on in its Shopify app and its own pickup lead time. A
store's quotes count against the same daily quote budget as its Shopify app. A
rate has no book_url.
origin_id names one of the store's ship-from points from GET /origins
(manual, or loc_ and a number). A store keeps no saved destinations, so
destination_id is refused; send destination_postal_code and
destination_state. A destination street sent with a quote is kept with that
quote only, never saved.
Booking#
POST /bookings books a quote the store's key created, for a lane or for one of
its orders (see Orders). A quote made in the Shopify app itself is
booked there (booking_not_allowed); rate the order with quote_order to book
it here. As for an organization, what the body leaves out comes from the
quote: its stops, the day it was rated for and, when no pickup_window is sent,
the store's own pickup window. Whatever is still missing is named per field.
Over MCP a store's answers show as ShipEasy cards in store mode (see
MCP cards): Book starts the Shopify charge and the
card asks the person to approve it in Shopify. Its prompt is ship_order. POST /bookings/preview (MCP preview_booking) is not offered to a store
(not_available_for_shopify): Shopify's approval page shows the total before
anything is charged. expected_amount_usd is checked against the rate's price
(price_changed, with new_amount_usd); with coverage elected, the approval
page shows the total with the premium.
Each booking is a Shopify app charge, so the answer is always 202 with
status: "requires_authentication" and an authenticate_url: Shopify's page
where the store approves the charge. Open it signed in to Shopify admin as
someone who can approve app charges, or send it to them. Nothing is charged or
booked until then. Then poll GET /bookings/{id}; polling settles the charge,
and the booking becomes booked. An approval page left unanswered for 48 hours
expires, and the booking reads expired.
payment is ignored. Booking needs the bookings:write scope and counts
against the store's daily booking ceiling.
Cancelling#
POST /shipments/{id}/cancel records the store's request, as the Shopify app
does. Nothing is cancelled until the carrier confirms; a store's refund comes
back as ShipEasy credit.