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
Choose-Signup-method Image
Main-Identifier-Email Image
Main-Identifier-Phone Image
Provide-OTP Image

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:

customers/check-email

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:

customers/check-phone-number

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 a 429 comes back.

Some brands also require a g-recaptcha-response on 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:

customers/login

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:

legal-agreement-acceptances

{
  "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:

legal-agreement-acceptances

{
  "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:

customers/login

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:

legal-agreement-acceptances

{
  "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:

legal-agreement-acceptances

{
  "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:

customers/invalidate-login

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
}