Skip to content

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 in payment.payment_method_id; when exactly one card is enabled for API bookings you may leave payment out and that card is used.
  • invoice — ShipEasy bills your company off-platform on your agreed terms. No card is involved: omit payment entirely. One sent anyway is ignored.

Two things must be true before your first API booking:

  1. Someone with authority has accepted the terms in the web app (booking.terms_accepted on GET /account).
  2. On the card mode 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#

POST/api/v1/bookingsScope bookings:write
Request
curl -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…" }
  }'
Response
{
	"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):

JSON
{
	"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 address1 and you replace the quoted company, address1, address2 and city whole, 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 example destination.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#

POST/api/v1/bookings/previewScope bookings:write
Request
curl https://app.shipeasyco.com/api/v1/bookings/preview \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "quote_id": "cm2k8r9f2…" }'
Response
{
	"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.

  • ready is true when booking with this same body would go through — unless the carrier's live rate has moved since you quoted.
  • issues names each field still missing or wrong (destination.phone), with a sentence saying what it is. Fill them and preview again.
  • blockers are about the account, as on GET /account, each with the fix_url that fixes it.
  • expected_amount_usd is freight plus coverage, before any promo credit: the most the booking will charge. Send it back as expected_amount_usd when you book, and a booking whose total has moved since is refused with 409 price_changed before 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:

JSON
"insurance": { "declared_value_usd": 12500, "accept_terms": true }
  • declared_value_usd — what the goods are worth. It must sit between insurance.min_declared_value_usd and insurance.coverage_limit_usd on GET /account; above the limit we cannot insure online.
  • accept_terms — must be true, on every request that buys coverage. It is your acceptance of the conditions in insurance.terms on GET /account (version insurance.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#

GET/api/v1/bookings/{chargeId}Scope bookings:read
curl https://app.shipeasyco.com/api/v1/bookings/cm2k8t5c1… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"

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.

Python
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:

JSON
{
	"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_url is 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 /bookings for the same quote answers 409 quote_already_booked with this booking_id.
  • Only the POST /bookings reply carries it. GET /bookings/{id} returns authenticate_url: null (the expiry is still there). Store the link from the POST reply.
  • 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_authentication webhook tells you it happened, but it does not carry the link. Route authenticate_url to 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.