Customer

Authenticate a Customer ❗

Authenticates a storefront customer with an email or phone identity and password. The response includes the customer profile and an auth token.

curl -X POST https://api.fleetbase.io/v1/customers/login \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "identity": "{{customer_identity}}",
  "password": "{{customer_password}}"
}'

Authenticate a Customer via SMS

Starts SMS authentication for an existing storefront customer. A verification code is sent by SMS; if the text could not be sent (the store has no SMS provider configured, or the SMS guard refused it) and the customer has an email address on file, it is emailed instead. Exchange the code at Verify a SMS code (customers/verify-code) for an auth token. The code expires after ten minutes and can be used once.

phone is in E.164 format, with or without the leading + (no spaces or dashes). Response: { "status": "OK", "method": "sms" }, or "method": "email" when the code was emailed. Errors (400): no customer with this phone, or the code could not be sent. With no email to fall back to, the guard's refusal is returned as 429 or 423.

Endpoints that send a text are limited to five requests a minute per storefront key and client address, and every message passes the platform's SMS guard. A refused send returns 429 with a Retry-After header (a cooldown on that number, or the store's message budget) or 423 (text messages are paused for the store).

curl -X POST https://api.fleetbase.io/v1/customers/login-with-sms \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "{{customer_phone}}"
}'

{
  "status": "OK",
  "method": "sms"
}

Verify a SMS code

Verifies a code sent by SMS or email (sign-in or account creation). The response includes the customer profile and auth token when verification succeeds.

A code verifies once. Each wrong guess counts against the newest code issued for the identity; after five the code locks and a new one must be requested. After ten wrong codes for the same identity within fifteen minutes, from any address, the endpoint returns 429 until the window passes.

App store review accounts: when the server sets STOREFRONT_BYPASS_VERIFICATION_CODE and lists the identity in STOREFRONT_REVIEW_ACCOUNTS, that fixed code is accepted for those identities only, without sending a message.

Errors (400): no customer for the identity, or an invalid code.

curl -X POST https://api.fleetbase.io/v1/customers/verify-code \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "identity": "{{customer_identity}}",
  "code": "{{verification_code}}"
}'

Retrieve a Customer

Retrieves a storefront customer by ID. Only the customer signed in with the Customer-Token header can be retrieved; a storefront key alone is refused with 401.

curl https://api.fleetbase.io/v1/customers \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

Setups a verification request to create a new storefront custome

Sends a verification code to start a storefront customer sign-up. The code is required when creating the customer account; it expires after ten minutes and can be used once.

Returns 422 when an account already exists for the identity (send the customer to sign in instead), or when the phone number is invalid or cannot receive a text message. Asking again for the same identity within sixty seconds returns { "status": "ok" } without sending a second message, so a retry button is safe to offer.

Endpoints that send a text are limited to five requests a minute per storefront key and client address, and every message passes the platform's SMS guard. A refused send returns 429 with a Retry-After header (a cooldown on that number, or the store's message budget) or 423 (text messages are paused for the store).

curl -X POST https://api.fleetbase.io/v1/customers/request-creation-code \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "email",
  "identity": "{{creation_code_identity}}"
}'

{
  "status": "ok"
}

Register customer device

Registers a push notification device token for the authenticated storefront customer. Call it whenever the app receives a new token or a different customer signs in: a token identifies one app install, so it always moves to the customer who registered it most recently. platform must be ios or android (case insensitive); the token is an APNs device token on iOS and an FCM registration token on Android. Returns { "status": "OK", "device": "<device public id>" }, or 400 for a missing token or unsupported platform.

curl -X POST https://api.fleetbase.io/v1/customers/register-device \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "token": "{{device_token}}",
  "platform": "ios"
}'

Unregister customer device

Removes a push notification device token from the authenticated customer, typically on sign out, so the device stops receiving that customer's notifications. Returns { "status": "OK", "deleted": n }; unregistering a token the customer does not have deletes nothing and is not an error.

curl -X POST https://api.fleetbase.io/v1/customers/unregister-device \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "token": "{{device_token}}"
}'

Create Customer Socket Token

Creates a short-lived token for the authenticated customer to authenticate the realtime (SocketCluster) connection. With it the customer may subscribe to their storefront's channel, their own checkouts (checkout.{id}) and the chats they take part in (chat.{id}, see Order Chat). Fetch a new one before expires_at.

Response: { "token": "<JWT>", "expires_in": 900, "expires_at": "2026-10-12T10:15:00+00:00" }. expires_in is in seconds (900 by default, at most 3600).

Errors: 404 when the server doesn't have socket authentication enabled (clients then connect anonymously), 401 without a valid Customer-Token or for a customer of another company.

curl -X POST https://api.fleetbase.io/v1/customers/socket-token \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{}'

Authenticate a Customer with Apple

Authenticates a storefront customer with Apple Sign-In. Fleetbase verifies the Apple identity token, creates or updates the user, and returns the storefront customer with an auth token.

curl -X POST https://api.fleetbase.io/v1/customers/login-with-apple \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "identityToken": "{{apple_identity_token}}",
  "authorizationCode": "{{apple_authorization_code}}",
  "email": "{{customer_email}}",
  "phone": "{{customer_phone}}",
  "name": "{{customer_name}}",
  "appleUserId": "{{apple_user_id}}"
}'

Authenticate a Customer with Facebook

Authenticates a storefront customer with Facebook account data. Fleetbase creates or updates the matching user and returns the storefront customer with an auth token.

curl -X POST https://api.fleetbase.io/v1/customers/login-with-facebook \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "{{customer_email}}",
  "name": "{{customer_name}}",
  "facebookUserId": "{{facebook_user_id}}"
}'

Authenticate a Customer with Google

Authenticates a storefront customer with Google Sign-In. Fleetbase verifies the Google ID token, creates or updates the user, and returns the storefront customer with an auth token.

curl -X POST https://api.fleetbase.io/v1/customers/login-with-google \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "idToken": "{{google_id_token}}",
  "clientId": "{{google_client_id}}"
}'

Query customers

Returns the customer signed in with the Customer-Token header. A storefront key alone is refused with 401: it does not list the company's customers.

curl https://api.fleetbase.io/v1/customers \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

Create a Customer

Creates a storefront customer after verifying the supplied creation code. The response includes the customer profile and an auth token.

curl -X POST https://api.fleetbase.io/v1/customers \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "{{customer_name}}",
  "email": "{{new_customer_identity}}",
  "code": "{{verification_code}}"
}'

Get Stripe Ephemeral Key

Creates a Stripe ephemeral key for the authenticated storefront customer. Fleetbase creates the Stripe customer first when the customer does not already have one.

curl -X POST https://api.fleetbase.io/v1/customers/stripe-ephemeral-key \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{}'

Get Stripe Setup Intent

Creates a Stripe SetupIntent for the authenticated storefront customer. Use the returned client secret to collect or update a saved payment method.

curl -X POST https://api.fleetbase.io/v1/customers/stripe-setup-intent \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{}'

Start Account Closure

Starts storefront account closure for the authenticated customer. Fleetbase sends a verification code to the linked phone number, or to the linked email address when the text could not be sent (no SMS provider configured, or the SMS guard refused it). The code expires after ten minutes and can be used once.

Endpoints that send a text are limited to five requests a minute per storefront key and client address, and every message passes the platform's SMS guard. A refused send returns 429 with a Retry-After header (a cooldown on that number, or the store's message budget) or 423 (text messages are paused for the store).

curl -X POST https://api.fleetbase.io/v1/customers/account-closure \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{}'

Update a Customer

Updates the authenticated storefront customer's profile. The Customer-Token identity is authoritative and must belong to the customer addressed by customer_id; missing or mismatched customer credentials return 403 Not authorized to update customer. The response returns the customer with the new values applied.

curl -X PUT https://api.fleetbase.io/v1/customers \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "name": "Jane Doe"
}'

Confirm Account Closure

Confirms storefront account closure using the verification code sent to the customer. Fleetbase deletes the customer contact and, for customer users, the linked user account.

The code verifies once and locks after five wrong guesses; after ten wrong codes for the customer within fifteen minutes the endpoint returns 429.

curl -X POST https://api.fleetbase.io/v1/customers/confirm-account-closure \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "code": "{{verification_code}}"
}'

Request Phone Verification

Sends a verification code to a new phone number for the authenticated storefront customer. Returns 422 when the number is invalid, cannot receive a text message, or is already assigned to another account. Response: { "status": "ok" }. The code expires after ten minutes and can be used once. For an app store review account (listed in STOREFRONT_REVIEW_ACCOUNTS, with STOREFRONT_BYPASS_VERIFICATION_CODE set), no SMS is sent and the response is { "status": "ok", "method": "bypass" }.

Endpoints that send a text are limited to five requests a minute per storefront key and client address, and every message passes the platform's SMS guard. A refused send returns 429 with a Retry-After header (a cooldown on that number, or the store's message budget) or 423 (text messages are paused for the store).

curl -X POST https://api.fleetbase.io/v1/customers/request-phone-verification \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "phone": "{{customer_phone}}"
}'

Verify Phone Number

Verifies the customer's pending phone number with the code sent by the phone verification request. The code verifies once and locks after five wrong guesses; after ten wrong codes for the customer within fifteen minutes the endpoint returns 429.

curl -X POST https://api.fleetbase.io/v1/customers/verify-phone-number \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "phone": "{{customer_phone}}",
  "code": "{{verification_code}}"
}'

List a customer saved places

Returns saved places for the authenticated storefront customer. Use these places for delivery addresses and checkout defaults.

curl https://api.fleetbase.io/v1/customers/places \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

Update Contact Customer Alias

Updates the authenticated storefront customer through the legacy contact alias route. The request is handled by the same customer update controller as /customers/{id} and carries the same authorization contract: the Customer-Token must belong to the customer addressed by customer_id, and missing or mismatched customer credentials return 403 Not authorized to update customer.

curl -X PUT https://api.fleetbase.io/v1/contacts \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "name": "{{customer_name}}",
  "email": "{{customer_email}}",
  "phone": "{{customer_phone}}"
}'

List a customer orders

Returns orders that belong to the authenticated storefront customer. Use pagination and filters to browse the customer order history.

For a network key, a checkout across several stores appears once, as its master order (meta.is_master_order, meta.related_orders); the stores' own orders are left out. Use GET orders/{id}/stores for the per-store breakdown. Order meta can include checkout_id, discount, promotions, payment_status, is_booking, booking_at and booking_has_items.

curl https://api.fleetbase.io/v1/customers/orders \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"