Customer Sign-In Flow
Introduction
A brand authenticates its customers either by email or by phone number. The choice is part of the brand's authentication method settings; it is made when the brand is created and cannot be changed later, so your app only ever needs to implement the one flow that applies.
The two flows are the same shape: check whether the customer exists, send a one-time code, sign in with the code. They differ only in which identifier the customer types first. The email address is the unique identifier of a customer account on both kinds of brand.
| Choose the Sign In method | Provide the Main Identifier (Email) | Provide the Main Identifier (Phone) | Provide The One time password |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
Check if the customer account already exists in the system
On an email brand, find out whether the customer already has an account by passing their email to:
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
email |
varchar | "john.doe@gmail.com" |
Customer's email address |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/customers/check-email",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json"
},
"body": {
"email": "john.doe@gmail.com"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"exists": false,
"is_social": false
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
exists |
boolean | true |
Whether an account with this email already exists |
is_social |
boolean | false |
Whether that account was created through a social login |
If exists is true, continue with sign-in below. If it is false, send the customer to the Sign Up flow.
On a phone number brand, pass the customer's phone number instead:
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
phone_number |
varchar | "+15852826524" |
Customer's phone number |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/customers/check-phone-number",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json"
},
"body": {
"phone_number": "+15852826524"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"exists": false,
"is_social": false
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
exists |
boolean | true |
Whether an account with this phone number already exists |
is_social |
boolean | false |
Whether that account was created through a social login |
As with email: exists: true means sign in, exists: false means sign up.
Phone numbers must be in E.164 format — a leading +, a valid country code, then the national number, as in +15852826524. Numbers that are too short, too long, missing the + or starting with an unknown country code are rejected.
Sign in for a Brand that uses Email customer authentication method
Signing in starts by sending the customer a one-time code. Pass their email to:
customers/passwordless-request
This endpoint is throttled. A given email or phone number can request a code 3 times per minute, and there is a looser per-IP cap of 30 per minute. Exceeding either returns
429. Put a short cooldown on your "resend code" button rather than letting the customer tap it repeatedly, and surface a clear message when a429comes back.Some brands also require a
g-recaptcha-responseon this call. Whether it applies depends on the brand configuration, so handle the rejection rather than assuming it is never needed.
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
email |
varchar | "john.doe@gmail.com" |
Customer's email address |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/customers/passwordless-request",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json"
},
"body": {
"email": "john.doe@gmail.com"
}
}
Response
{
"status": "OK",
"code": 200
}
You can resend the code to the customer by calling the same route.
Then sign the customer in with the code they received:
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
passwordless_email |
varchar | "john.doe@gmail.com" |
Customer's email address |
passwordless_code |
varchar | "053631" |
One time password that was sent to customer's email |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/customers/login",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json"
},
"body": {
"passwordless_email": "john.doe@gmail.com",
"passwordless_code": "053631"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"customer_account": {
"id": "0ff757dd-9b8a-4750-89ad-03ff531ae923",
"type_id": 1,
"reference_type": "CustomerAccount",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@gmail.com",
"phone_number": "",
"locale": "en-US",
"state": 1,
"demographics": [],
"optin_status_email": 3,
"optin_status_pn": 3,
"has_pending_email_change": false,
"has_pending_phone_number_change": false,
"is_social": false,
"social_login": null,
"updated_at": "2023-08-24 15:33:27",
"created_at": "2023-08-24 15:33:27"
},
"token": {
"value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXRSZWZyZXNoVFRMIjoyNjI4MDAwLCJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvY3VzdG9tZXJzL2xvZ2luIiwiaWF0IjoxNjkyODkzNTkxLCJleHAiOjE2OTI4OTcxOTEsIm5iZiI6MTY5Mjg5MzU5MSwianRpIjoiT0VsUnNpMXFMYzFaRUkxSCIsInN1YiI6IjUwOTA5NjUiLCJwcnYiOiJjYzMyOTIxYTE1NDgwYTExN2Q5YmJjNzJjMGUxMjU2YTY4NTI0NThiIiwiYXBwbGljYXRpb25faWQiOjIwMTUsInNlc3Npb25faWQiOjI4MjYwfQ.fmHQbNHH4Cd4l1HaWHzavJwGTAImtE2HsC6a3_QUHZc",
"ttl": 60,
"issued_token_type": "access_token",
"token_type": "Bearer"
},
"dlc_access_token": null
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
locale |
varchar [5] | "en-US" | Customer's location used to show the appropriate translations. |
token |
CustomerAccountToken | The customer token for the Authorization header. See How to Refresh Customer Token. |
|
dlc_access_token |
CustomerAccountToken | null | null |
On a brand integrated with Punchh, the Punchh token for the Dlc-Authorization header. null on every other brand. |
Once the customer is signed in, check whether this device has accepted the brand's Terms of Service and Privacy Policy:
{
"method": "get",
"url": "https://api-public-demo.menu.app/api/legal-agreement-acceptances/check",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json",
"Device-UUID": "1287796"
}
}
Response
{
"status": "OK",
"code": 200
}
The call returns 200 when the device has accepted the brand's current terms, and 400 with code 4016 (Legal agreement acceptance required) when it has not. On a 4016, show the Terms of Service and Privacy Policy, and record the acceptance once the customer agrees:
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/legal-agreement-acceptances",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json",
"Device-UUID": "1287796"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"legal_agreement_acceptance": {
"id": "c2635178-1ec0-41d4-9a0b-f85ed7f0659c",
"device_uuid": "1287796"
}
}
}
Sign in for a Brand that uses Phone number customer authentication method
Signing in starts by sending the customer a one-time code by SMS. Pass their phone number to:
customers/passwordless-request
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
phone_number |
varchar | "+15852826524" |
Customer's phone number |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/customers/passwordless-request",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json"
},
"body": {
"phone_number": "+15852826524"
}
}
You can resend the code to the customer by calling the same route.
Then sign the customer in with the code they received:
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
phone_number |
varchar | "+15852826524" |
Customer's phone number |
passwordless_code |
varchar | "053631" |
One time password that was sent to customer's phone number |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/customers/login",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json"
},
"body": {
"phone_number": "+15852826524",
"passwordless_code": "053631"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"customer_account": {
"id": "cbe252fe-3757-4b53-9e3b-c13ee84f65bc",
"type_id": 1,
"reference_type": "CustomerAccount",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@gmail.com",
"phone_number": "+15852826524",
"locale": "en",
"state": 1,
"demographics": [],
"optin_status_email": 3,
"optin_status_pn": 3,
"has_pending_email_change": false,
"has_pending_phone_number_change": false,
"is_social": false,
"social_login": null,
"updated_at": "2023-08-03 10:22:42",
"created_at": "2023-08-01 16:09:10"
},
"token": {
"value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXRSZWZyZXNoVFRMIjoyNjI4MDAwLCJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvY3VzdG9tZXJzL2xvZ2luIiwiaWF0IjoxNjkyOTYwNzQxLCJleHAiOjE2OTI5NjQzNDEsIm5iZiI6MTY5Mjk2MDc0MSwianRpIjoiaEN4MUFERzNPT2RpbnlOMCIsInN1YiI6IjUwOTA1MjciLCJwcnYiOiJjYzMyOTIxYTE1NDgwYTExN2Q5YmJjNzJjMGUxMjU2YTY4NTI0NThiIiwiYXBwbGljYXRpb25faWQiOjIxNDQsInNlc3Npb25faWQiOjI4MjkzfQ.kdhLb6c5QEGxs1j2oqcVJFmxQ3xAAB81-CPaXmaW0FY",
"ttl": 60,
"issued_token_type": "access_token",
"token_type": "Bearer"
},
"dlc_access_token": null
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
locale |
varchar [5] | "en-US" | Customer's location used to show the appropriate translations. |
token |
CustomerAccountToken | The customer token for the Authorization header. See How to Refresh Customer Token. |
|
dlc_access_token |
CustomerAccountToken | null | null |
On a brand integrated with Punchh, the Punchh token for the Dlc-Authorization header. null on every other brand. |
Once the customer is signed in, check whether this device has accepted the brand's Terms of Service and Privacy Policy:
{
"method": "get",
"url": "https://api-public-demo.menu.app/api/legal-agreement-acceptances/check",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json",
"Device-UUID": "1287796"
}
}
Response
{
"status": "OK",
"code": 200
}
The call returns 200 when the device has accepted the brand's current terms, and 400 with code 4016 (Legal agreement acceptance required) when it has not. On a 4016, show the Terms of Service and Privacy Policy, and record the acceptance once the customer agrees:
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/legal-agreement-acceptances",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json",
"Device-UUID": "1287796"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"legal_agreement_acceptance": {
"id": "c2635178-1ec0-41d4-9a0b-f85ed7f0659c",
"device_uuid": "1287796"
}
}
}
To keep the customer signed in, refresh the token when it expires — see How to Refresh Customer Token.
Sign Out
To sign the customer out, invalidate their token:
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Authorization HTTP header |
string | "Bearer {customer_account_token}" |
JWT Token of Customer Account |
{
"method": "get",
"url": "https://api-public-demo.menu.app/api/customers/invalidate-login",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json",
"Device-UUID": "1287796",
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXRSZWZyZXNoVFRMIjoyNjI4MDAwLCJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvY3VzdG9tZXJzL2xvZ2luIiwiaWF0IjoxNjkyOTYyNDUxLCJleHAiOjE2OTI5NjYwNTEsIm5iZiI6MTY5Mjk2MjQ1MSwianRpIjoiRk4wY0xJdU5FU0VxNThtYiIsInN1YiI6IjUwOTA1MjciLCJwcnYiOiJjYzMyOTIxYTE1NDgwYTExN2Q5YmJjNzJjMGUxMjU2YTY4NTI0NThiIiwiYXBwbGljYXRpb25faWQiOjIxNDQsInNlc3Npb25faWQiOjI4Mjk5fQ.BW6FiRxXNsCMO1nUs2ec22NGU8y-xsVoAKskQpSrnok"
}
}
Response
{
"status": "OK",
"code": 200
}




