How to Refresh Customer Token

Signing in gives you a customer token, and every customer-scoped call carries it on the Authorization header. The token object tells you how long it lives: ttl is the lifetime in minutes, and it is set per environment, so read it from the response rather than hard-coding a number.

An expired token is not dead. It can be refreshed for a long time after it expires — the refresh window is measured in years — so in practice you refresh until a refresh call fails, and only then send the customer back to sign in:

customers/refresh


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/refresh",
  "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.eyJzZXRSZWZyZXNoVFRMIjoyNjI4MDAwLCJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvY3VzdG9tZXJzL2xvZ2luIiwiaWF0IjoxNjkzMjA3MjA1LCJleHAiOjE2OTMyMTA4MDUsIm5iZiI6MTY5MzIwNzIwNSwianRpIjoiZUNUNGlZcVZKTGFmdlNIYSIsInN1YiI6IjUwOTA5NzYiLCJwcnYiOiJjYzMyOTIxYTE1NDgwYTExN2Q5YmJjNzJjMGUxMjU2YTY4NTI0NThiIiwiYXBwbGljYXRpb25faWQiOjIxNDQsInNlc3Npb25faWQiOjI4MzUwfQ.0WWTS1RxwPELOPIHV6MAB-XYQCsG7ocS1XvRvc5Vc6w"

  }
  
}

Response

{
  "status": "OK",
  "code": 200,
  "data": {
    "customer_account": {
      "id": "8100bab1-267e-41ae-8592-c229253b0129",
      "type_id": 1,
      "reference_type": "CustomerAccount",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@gmail.com",
      "phone_number": "+15852826525",
      "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-28 07:29:58",
      "created_at": "2023-08-25 12:10:33"
    },
    "token": {
      "value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvY3VzdG9tZXJzL3JlZnJlc2giLCJpYXQiOjE2OTMyMDcyMDUsImV4cCI6MTY5MzIxMTgwOSwibmJmIjoxNjkzMjA4MjA5LCJqdGkiOiJxcFluSXQxSVVZOEFnSnVqIiwic2V0UmVmcmVzaFRUTCI6MjYyODAwMCwic3ViIjoiNTA5MDk3NiIsInBydiI6ImNjMzI5MjFhMTU0ODBhMTE3ZDliYmM3MmMwZTEyNTZhNjg1MjQ1OGIiLCJhcHBsaWNhdGlvbl9pZCI6MjE0NCwic2Vzc2lvbl9pZCI6MjgzNTB9.BHtPDBaiMtWZyi99_dZYnDgSJzsHuMtoIbDiF0z9gco",
      "ttl": 60,
      "issued_token_type": "access_token",
      "token_type": "Bearer"
    },
    "dlc_access_token": null
  }
}
Attribute Type Description
token object The new PAR Ordering customer token, for the Authorization header. ttl is in minutes.
dlc_access_token object | null The new Punchh token, for the Dlc-Authorization header. Populated on a brand integrated with Punchh and null on every other brand, as in the example above. Refresh renews both, so replace both headers. See Authenticating to Punchh.

A session created by the STS token exchange cannot be refreshed. The request is rejected with 403 and the token is invalidated — run the exchange again instead.

Refresh accepts an expired token or a live one. Either way the old token stops working the moment the new one is issued, so store the new value before you retry anything. To end a session without issuing a new token — on sign-out, for example — call Invalidate Login instead.

What a 401 is telling you

Every call that takes the Authorization header answers 401 the same way: info_message.title says what kind of failure it is and info_message.body says why. Branch on the body, because the right reaction differs.

info_message Meaning What to do
Unauthorized access / JWT token expired. The token's ttl has passed. Call refresh with the expired token, store the new one, retry the request. If the session came from the STS token exchange, refresh answers 403 instead — run the exchange again.
Unauthorized access / JWT token invalid. The token is malformed, was issued for a different Application key, or its session is gone because it was refreshed or signed out elsewhere. Refresh will not help. Clear the stored token and send the customer to sign in.
Internal error! / JWT token expired. Returned by refresh itself: the token is past its refresh window. The window is years long, so this means a very old token. Send the customer to sign in.
Internal error! / JWT token invalid. Returned by refresh itself: the token is no longer the current one for its session, typically because it was already refreshed once and you retried with the old value. Use the token from the first refresh if you still have it; otherwise send the customer to sign in.
AdvanceAuthTokenMismatchError / Token has expired or Token Signature could not be verified Only on brands using PAR Guest Identity, where the Authorization token comes from the identity provider. The token expired or was not signed by a key we trust, which usually means a token from the wrong environment or wrong brand. Sign the customer in again; these tokens are not refreshed through this endpoint.

Guard against refreshing in a loop: a client that answers every 401 with a refresh and a retry will hammer the API when the token is invalid rather than expired. Refresh once, and if the retry is 401 again, sign the customer out.