Booking
Contents 26 pages
Booking buys a quote. It is the one endpoint that commits your organization to spending money, so read this page before you write the code.
How the money is settled depends on your organization, and GET /account
reports it as booking.billing_mode:
card(the default) — the booking charges a card you have already authorized. Name it inpayment.payment_method_id; when exactly one card is enabled for API bookings you may leavepaymentout and that card is used.invoice— ShipEasy bills your company off-platform on your agreed terms. No card is involved: omitpaymententirely. One sent anyway is ignored.
Two things must be true before your first API booking:
- Someone with authority has accepted the terms in the web app
(
booking.terms_acceptedonGET /account). - On the
cardmode only: at least one saved card has been enabled for API bookings — a separate, deliberate authorization. See payment methods & mandates.
GET /account tells you where you stand before you quote: booking.ready is
true when nothing about the account stops a booking, and otherwise
booking.blockers lists each reason with the error code a booking would answer
and a fix_url, the web app page where a person fixes it. booking.payment
says how it will be paid, and names the card used when you name none.
A Shopify store's booking is a Shopify charge the store approves: it answers requires_authentication with Shopify's approval page. See Shopify stores.
The prices and ids in the examples below are illustrative, made up for the example.
Book a quote#
/api/v1/bookingsScope bookings:writecurl -X POST https://app.shipeasyco.com/api/v1/bookings \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8f14e45f-ea0f-4a3e-9c7a-2b1d0a6c5e33" \
-d '{
"quote_id": "cm2k8r9f2…",
"origin": {
"name": "Dock A",
"company": "Acme Freight",
"address1": "1200 Devon Ave",
"city": "Elk Grove Village",
"state": "IL",
"postal_code": "60007",
"phone": "+1-847-555-0100"
},
"destination": {
"name": "Rita Chen",
"company": "Northline Supply",
"address1": "4100 Commerce St",
"city": "Dallas",
"state": "TX",
"postal_code": "75201",
"phone": "+1-214-555-0188",
"email": "receiving@northline.example"
},
"pickup_date": "2026-11-17",
"pickup_window": "full-day",
"customer_reference": "SO-1041",
"origin_instructions": "Drive up dock at rear of building",
"delivery_instructions": "Call 30 minutes ahead",
"payment": { "payment_method_id": "cm2k7p3q0…" }
}'const res = await fetch("https://app.shipeasyco.com/api/v1/bookings", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SHIPEASY_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "8f14e45f-ea0f-4a3e-9c7a-2b1d0a6c5e33",
},
body: JSON.stringify({
quote_id: "cm2k8r9f2…",
origin: {
name: "Dock A",
company: "Acme Freight",
address1: "1200 Devon Ave",
city: "Elk Grove Village",
state: "IL",
postal_code: "60007",
phone: "+1-847-555-0100",
},
destination: {
name: "Rita Chen",
company: "Northline Supply",
address1: "4100 Commerce St",
city: "Dallas",
state: "TX",
postal_code: "75201",
phone: "+1-214-555-0188",
email: "receiving@northline.example",
},
pickup_date: "2026-11-17",
pickup_window: "full-day",
customer_reference: "SO-1041",
origin_instructions: "Drive up dock at rear of building",
delivery_instructions: "Call 30 minutes ahead",
payment: { payment_method_id: "cm2k7p3q0…" },
}),
});
const booking = await res.json();import os
import requests
res = requests.post(
"https://app.shipeasyco.com/api/v1/bookings",
headers={
"Authorization": f"Bearer {os.environ['SHIPEASY_API_KEY']}",
"Idempotency-Key": "8f14e45f-ea0f-4a3e-9c7a-2b1d0a6c5e33",
},
json={
"quote_id": "cm2k8r9f2…",
"origin": {
"name": "Dock A",
"company": "Acme Freight",
"address1": "1200 Devon Ave",
"city": "Elk Grove Village",
"state": "IL",
"postal_code": "60007",
"phone": "+1-847-555-0100",
},
"destination": {
"name": "Rita Chen",
"company": "Northline Supply",
"address1": "4100 Commerce St",
"city": "Dallas",
"state": "TX",
"postal_code": "75201",
"phone": "+1-214-555-0188",
"email": "receiving@northline.example",
},
"pickup_date": "2026-11-17",
"pickup_window": "full-day",
"customer_reference": "SO-1041",
"origin_instructions": "Drive up dock at rear of building",
"delivery_instructions": "Call 30 minutes ahead",
"payment": {"payment_method_id": "cm2k7p3q0…"},
},
)
booking = res.json(){
"object": "booking",
"id": "cm2k8t5c1…",
"reference": "PCH-K7QD9M3",
"status": "processing",
"amount_usd": "1285.00",
"currency": "USD",
"quote_id": "cm2k8r9f2…",
"shipment_id": null,
"decline_code": null,
"authenticate_url": null,
"authenticate_expires_at": null,
"next_step": "Paid; the carrier booking is still finishing. Poll this booking again in a few seconds.",
"paid_at": null,
"booked_at": null,
"created_at": "2026-11-12T14:05:01.000Z",
"updated_at": "2026-11-12T14:05:01.000Z",
"insurance": null,
"refund": null
}Note: The response is 202, not 201. The money is committed — the card
charged, or the amount booked to your account — and the carrier booking may
still be finishing. Poll GET /bookings/{id} until status is booked, then
read shipment_id.
paid_at is null until we confirm the card payment, which happens on your
first poll at the latest.
On the invoice mode there is no payment to wait for, so the carrier booking
starts within the request: the reply can already be booked with shipment_id
set, or failed; branch on status as always. While it is processing,
next_step says so without claiming a payment, and paid_at is when the
booking was billed to your account (nothing is charged):
{
"status": "processing",
"next_step": "Billed on account; the carrier booking is still finishing. Poll this booking again in a few seconds.",
"paid_at": "2026-11-12T14:05:02.000Z"
}Requires bookings:write and an Idempotency-Key.
The request#
| Field | ||
|---|---|---|
quote_id |
required | From a rate you got back from POST /quotes. |
origin |
Where it ships from. Optional: fills from the quote. See What the quote fills in. | |
destination |
Where it goes. Optional: fills from the quote. | |
pickup_date |
YYYY-MM-DD |
Defaults to the day the quote was rated for, the only day it can be booked for. Must respect your organization's pickup lead time. |
pickup_window |
A preset id — full-day, morning or afternoon — or custom:HH:MM-HH:MM in 24-hour time spanning at least 4 hours. Defaults to your organization's own pickup window, as the web app does. |
|
customer_reference |
Your own reference. Travels onto the BOL and comes back on the shipment. Max 50 characters. | |
origin_instructions |
What the driver needs in order to collect — which dock, which gate, who to ask for. Printed on the BOL as ORIGIN INSTRUCTIONS. Max 200 characters. | |
delivery_instructions |
What the driver needs at delivery — gate code, floor, call ahead. Printed on the BOL after the delivery service. Max 200 characters. | |
requested_delivery_from |
YYYY-MM-DD |
The first day the receiver prefers delivery. No earlier than the quote's transit allows from pickup_date, and at most 15 business days past that. A preference passed to the carrier, not a guaranteed date: the carrier sets the appointment. |
requested_delivery_to |
YYYY-MM-DD |
The last day that works. Defaults to requested_delivery_from. |
requested_delivery_note |
Times that work for the receiver, such as weekday mornings. Needs requested_delivery_from. Max 300 characters. |
|
payment.payment_method_id |
on card |
ShipEasy's id for a card from GET /payment_methods with mit_enabled: true — not Stripe's pm_… id. Optional when exactly one card is enabled (booking.payment.default_card on GET /account); required when several are. Omit the whole payment object when billing_mode is invoice. |
insurance |
Buys cargo coverage. Omit it to book without. See Cargo coverage. | |
expected_amount_usd |
number | The total the person approved, from the preview. A booking that now totals anything else is refused with 409 price_changed, and nothing is charged. |
hazmat_certified |
boolean | Required as true when the quote declares a hazmat unit; ignored otherwise. See Hazardous materials. |
A booking needs name, address1, city, state, postal_code and
phone on both stops; company, address2, email and country (default
US) are optional. contact_name is accepted as another word for name — send
one or the other. Limits: name 80 characters; company, address1,
address2 and city 120; state 2; postal_code 10; phone 32; email 254.
What the quote fills in#
A quote keeps what you told it about the stops — a saved origin or destination
named by id, or the street and contact sent with origin and destination —
and the day it was rated for. A booking fills from that, so when the quote
holds both stops, quote_id alone books it (plus payment where a card must be
named):
- Send only what is missing or different. Contact fields (
name,phone,email) fill in one by one over what the quote holds. - A street moves as one block. Send
address1and you replace the quotedcompany,address1,address2andcitywhole, so a quoted suite or city never ends up beside a different street. - Whatever is still missing is named, per field, in one
400 validation_failed— for exampledestination.phone— with a sentence saying what it is.
missing_for_booking on the quote result lists the same fields before you try.
The stops must be on the quoted lane: origin.postal_code,
destination.postal_code and destination.state must match the quote. To change
them, re-quote.
The phone is required on both stops because the carrier refuses a booking without one — and if we let that through, the failure lands at the kerb rather than at the API.
There is no hosted-checkout fallback. A redirect needs a person, and the point of this endpoint is that there is not one.
A booking made here is uninsured unless the request carries insurance, even
when your organization insures by default in the web app.
amount_usd is the quote plus any coverage premium, less any promo credit your
organization holds. Your key's max_amount_usd ceiling, if it has one, is
checked against the total before the credit, and applies on both billing
modes. On invoice it is the only thing bounding an unattended booking: there is
no card issuer to refuse an amount.
Preview before you book#
/api/v1/bookings/previewScope bookings:writecurl https://app.shipeasyco.com/api/v1/bookings/preview \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "quote_id": "cm2k8r9f2…" }'{
"object": "booking_preview",
"quote_id": "cm2k8r9f2…",
"carrier": "CEVA Logistics",
"service": "Curbside Delivery",
"pickup_date": "2026-11-18",
"pickup_window": { "id": "full-day", "label": "Full day (8 AM – 5 PM PT)" },
"ready": false,
"issues": [
{
"field": "destination.phone",
"code": "required",
"message": "Required — The receiver's phone — the carrier calls before delivering and refuses a booking without one."
}
],
"blockers": [],
"freight_usd": "1285.00",
"credit_usd": null,
"expected_amount_usd": "1285.00",
"payment": {
"mode": "card",
"label": "Visa •••• 4242",
"card": { "brand": "visa", "last4": "4242" }
},
"note": "The rate is re-checked with the carrier when you book."
}The same body as POST /bookings, run through the booking's own checks, and
answered with exactly what booking it would do: both stops as they would be
sent to the carrier, the pickup day and window, coverage and its premium, how
it is paid and the total. It charges nothing, books nothing and does not
re-rate, so it needs no Idempotency-Key and costs no booking budget.
readyistruewhen booking with this same body would go through — unless the carrier's live rate has moved since you quoted.issuesnames each field still missing or wrong (destination.phone), with a sentence saying what it is. Fill them and preview again.blockersare about the account, as onGET /account, each with thefix_urlthat fixes it.expected_amount_usdis freight plus coverage, before any promo credit: the most the booking will charge. Send it back asexpected_amount_usdwhen you book, and a booking whose total has moved since is refused with409 price_changedbefore anything is charged.
A quote that cannot be booked at all answers as the booking would:
410 quote_expired, or 409 quote_already_booked / booking_already_paid
with the booking_id.
Requires bookings:write.
Cargo coverage#
Send insurance with the booking to buy shipper's-interest coverage, arranged
through Falvey Insurance Group:
"insurance": { "declared_value_usd": 12500, "accept_terms": true }declared_value_usd— what the goods are worth. It must sit betweeninsurance.min_declared_value_usdandinsurance.coverage_limit_usdonGET /account; above the limit we cannot insure online.accept_terms— must betrue, on every request that buys coverage. It is your acceptance of the conditions ininsurance.termsonGET /account(versioninsurance.terms_version): the declared value is accurate, the goods are not on the excluded list, the deductible applies, and until a certificate is issued only the carrier's released value covers the shipment (the premium is refunded if none is). Minting the key agreed to our booking terms, not to these, which is why it is asked for each time. The coverage summary has the exclusions, packing conditions and claims.
Price it first. GET /account publishes the price list under insurance:
the premium is the larger of minimum_premium_usd and declared value ×
rate_per_100_usd / 100, to the cent, and deductibles lists the bands. The
premium is added to amount_usd and counts toward your key's max_amount_usd.
The booking's insurance.premium_usd is the figure charged.
Pickup timing. The certificate is issued through our insurer's API when the
booking is paid, so any pickup from today (US Eastern) on can be insured, at any
hour. A pickup date that has passed cannot. insurance.bind_cutoff_hour_et is
always 24 and is kept only so clients that read it keep working.
Coverage is a request until a certificate exists. The booking's insurance
says what you bought. The shipment's coverage says whether it is real:
requested until the certificate is issued, then in_force with a
certificate_number. declined, cancelled and not_issued mean no cover; the
coverage summary says when the premium is refunded.
A refused election books nothing and costs no booking unit:
| Refusal | Code | issues[].field |
|---|---|---|
| Coverage cannot be sold right now | insurance_unavailable |
— |
accept_terms missing or not true |
validation_failed |
insurance.accept_terms |
| Value below the minimum or above the limit | validation_failed |
insurance.declared_value_usd |
| Pickup too soon to insure | validation_failed |
pickup_date |
Hazardous materials#
A quote whose handling_units declared hazmat (see
Quoting) books only with
"hazmat_certified": true. By sending it you certify, as the shipper, that the
materials are properly classified, described, packaged, marked and labeled, and
in proper condition for transportation under 49 CFR; that whoever prepared them
is trained under 49 CFR 172.704; and that the emergency phone given is answered
24 hours a day while they move. Without it the booking is refused before
anything is charged. The carrier receives each unit's UN number, class, packing
group and proper shipping name, and the emergency phone, for the BOL.
Polling a booking#
/api/v1/bookings/{chargeId}Scope bookings:readcurl https://app.shipeasyco.com/api/v1/bookings/cm2k8t5c1… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"const res = await fetch(`https://app.shipeasyco.com/api/v1/bookings/${bookingId}`, {
headers: { Authorization: `Bearer ${process.env.SHIPEASY_API_KEY}` },
});
const booking = await res.json();res = requests.get(
f"https://app.shipeasyco.com/api/v1/bookings/{booking_id}",
headers={"Authorization": f"Bearer {os.environ['SHIPEASY_API_KEY']}"},
)
booking = res.json()Requires bookings:read.
status |
Meaning | What to do |
|---|---|---|
processing |
Paid, the card payment is still clearing, or billed on account; the carrier booking is finishing. | Poll again in a few seconds. |
booked |
Done. shipment_id is set. |
Fetch the BOL. Stop polling. |
requires_authentication |
The bank wants the cardholder to verify. | See below. |
declined |
The card was declined. Nothing was charged. | Try another card. |
failed |
We could not complete it. | Our team has it. Contact support with the id. |
expired |
Not completed in time; released. | Request a fresh quote. |
refunded |
Stripe shows the whole payment refunded or on its way. A partial refund leaves status as it was; read refund. |
— |
Refunds. GET /bookings/{id} reads the card payment's refunds from Stripe
each time you fetch it and returns them in refund: refunded_usd is back on
the card, pending_usd is accepted by Stripe and still on its way. refund is
null in webhook bodies and the POST /bookings reply, on a booking billed on
account or with no card payment started, and when Stripe did not answer; fetch
again for it. A refunded booking whose refund.pending_usd is above zero says
so in next_step.
next_step on every booking is a sentence saying the same thing, so you can log
or surface it without maintaining your own status table. It is prose and its
wording can change (it differs by billing mode, for one): branch on status.
You do not have to poll for the outcome. A webhook
is sent when a booking reaches requires_authentication, declined, expired
or failed (booking.<status>, with the booking as data.object), and
booking.completed when it is booked.
booking = post("/api/v1/bookings", body, idempotency_key=key)
while booking["status"] == "processing":
time.sleep(3)
booking = get(f"/api/v1/bookings/{booking['id']}")
if booking["status"] == "booked":
pdf = get_bytes(f"/api/v1/shipments/{booking['shipment_id']}/bol")
elif booking["status"] == "requires_authentication":
notify_someone(booking["authenticate_url"], booking["authenticate_expires_at"])When the bank wants a person#
Sometimes an issuer insists the cardholder verify a charge, even one they pre-authorized. There is no way to satisfy that from a server, so we do not pretend otherwise:
{
"object": "booking",
"status": "requires_authentication",
"authenticate_url": "https://app.shipeasyco.com/portal/bookings/cm2k8t5c1…/authenticate?t=…",
"authenticate_expires_at": "2026-11-13T14:05:01.000Z",
"next_step": "The bank wants the cardholder to verify this payment. Open authenticate_url, or send it to someone who can, then poll this booking."
}- The freight is not booked and the card is not charged yet.
authenticate_urlis a one-time link, valid 24 hours. It works for whoever holds it — no web app sign-in is needed or used — so you can forward it to a cardholder who has no login. It opens a page with one button, Continue to your bank; nothing happens until it is pressed, so a mail scanner that opens the link does not touch the payment.- While the link is live the booking holds its quote:
POST /bookingsfor the same quote answers409 quote_already_bookedwith thisbooking_id. - Only the
POST /bookingsreply carries it.GET /bookings/{id}returnsauthenticate_url: null(the expiry is still there). Store the link from thePOSTreply. - Once they complete the challenge, everything continues on its own: the charge
settles, the carrier is booked, the confirmation email goes out. Your poll
will see
booked. - The
booking.requires_authenticationwebhook tells you it happened, but it does not carry the link. Routeauthenticate_urlto a person as soon as you get it, or the freight waits until the link expires. - If the link expires unused, the booking is released and you re-quote.
Treat this as a normal branch, not an error. Route the link to a human and keep polling.
Where the confirmation goes#
An API booking has no signed-in person to email, so we use your organization's
notification email, falling back to the contact email on the API key. If neither
exists we refuse with 400 notification_email_required before charging —
better than booking freight nobody is told about.
Refusals worth handling#
| Code | ||
|---|---|---|
validation_failed |
400 | A field is wrong, the stops or pickup date do not match the quote, or the date breaks your lead time. issues names the field. |
quote_expired |
410 | Re-quote and book the new rate. |
resource_not_found |
404 | No such quote for this organization, or the carrier no longer offers the rate. Re-quote. |
price_changed |
409 | The carrier's price moved. You are never charged an amount you were not quoted. |
quote_already_booked |
409 | Already booked, a booking is still settling, or one is waiting on the cardholder's bank. Poll booking_id if present. |
booking_already_paid |
409 | Paid but not yet booked — poll booking_id rather than paying again. |
insurance_unavailable |
409 | Coverage cannot be sold right now. Book without insurance. |
payment_outcome_unknown |
502 | The card may have been charged. Poll booking_id; never book the quote again. |
card_not_enabled_for_api |
402 | No card with that id is enabled for API bookings for this organization. Refused before a booking exists, so no webhook follows — unless the card was switched off while the request ran, when booking_id names the declined booking. |
card_declined |
402 | Nothing charged, nothing booked. message says why. booking_id names the declined booking; its booking.declined webhook carries the issuer's decline_code. |
terms_not_accepted |
403 | Someone with authority must accept the terms in the web app. |
billing_paused |
403 | Contact support. |
white_glove_not_approved |
403 | Request White Glove access in the web app. |
booking_amount_exceeds_key_limit |
403 | This key has a spending ceiling. Ask an admin to raise it, or use another key. |
booking_not_allowed |
403 | A setting on the account prevents it: the organization is inactive, the carrier is not enabled, or an agreed price no longer covers the carrier's cost. message says which. |
notification_email_required |
400 | Set a notification email on the organization or the key. |
daily_quota_exceeded |
429 | The organization's or this key's daily booking budget is spent. It resets at 00:00 UTC. |
rate_limit_exceeded |
429 | Too many booking attempts in a minute. Wait and retry. |
api_unavailable |
503 | Booking over the API is off or, for an organization that pays by card, card bookings are paused; or we could not count the booking against your daily budget. Nothing was charged; retry later. booking.enabled on GET /account says so. |
A note on responsibility#
An API booking is an unattended commitment — nobody is at a keyboard when the
money is spent. On the card mode that means the card is charged with no
cardholder present. That is exactly what makes headless booking possible, and it means
these charges do not carry the same fraud-liability protection as a payment
where the cardholder authenticated in the moment.
Practically: guard your API keys, use a per-key spending ceiling
(booking.max_amount_usd on /account shows the current one), and keep the
bookings:write scope off any key that does not need it.
On the invoice mode nothing is charged, and the ceiling matters MORE rather
than less: there is no issuer to refuse an amount, so the key's own limit is the
only thing standing between a bug in your integration and a large invoice.
A booking above the key's ceiling is refused with
booking_amount_exceeds_key_limit before the card is touched. The ceiling is a
maximum, not a bound: a booking exactly at the number is allowed.