This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

How to use paginated Toast API responses

The following procedure explains how to use paginated Toast API responses.

Using paginated Toast API responses

  1. Send a REST API request that returns a large number of data objects in its response. For example, GET requests to endpoints in the configuration API might return a large number of data objects for some restaurant configuration components.

  2. Get the token string for the next set of response objects from the Toast-Next-Page-Token header field in the response.

    If the response does not include a Toast-Next-Page-Token field, there are no more data objects in the response for your endpoint request and there is no next page to return.

    The following example shows the Toast-Next-Page-Token field in the header of a Toast API response.

    Date: Tue, 31 Aug 2021 21:16:09 GMT
    Content-Type: application/json
    Transfer-Encoding: chunked
    Connection: keep-alive
    X-Toast-RateLimit-By: API
    X-Toast-RateLimit-Remaining: 19
    X-Toast-RateLimit-Reset: 1630444570
    toast-next-page-token: Yzp7Imxhc3RUeXBlIjoiTWVudUl0ZW0iLCJsYXN0RXZhbHVhdGVkS2V5
      Ijp7IkFjdGl2ZVZlcnNpb25QSyI6eyJzIjoiUFVCTElTSCM3NmNiMWIwNS1jYjFlLTRhZGYtODYzY
      S1iMmE5NGE1ZWNkY2YjTWVudUl0ZW0iLCJuIjpudWxsLCJiIjpudWxsLCJtIjpudWxsLCJsIjpudW
      xsLCJicyI6bnVsbCwibnVsbCI6bnVsbCwiYm9vbCI6bnVsbCwic3MiOm51bGwsIm5zIjpudWxsfSw
      iU0siOnsicyI6Ik1lbnVJdGVtI2MxOTdmNTE3LWFjZTQtNDZjOC1hYWU2LTJlZDBkN2QwNjUyYiIs
      Im4iOm51bGwsImIiOm51bGwsIm0iOm51bGwsImwiOm51bGwsImJzIjpudWxsLCJudWxsIjpudWxsL
      CJib29sIjpudWxsLCJzcyI6bnVsbCwibnMiOm51bGx9LCJBY3RpdmVWZXJzaW9uMiI6eyJzIjoiYz
      E5N2Y1MTctYWNlNC00NmM4LWFhZTYtMmVkMGQ3ZDA2NTJiIiwibiI6bnVsbCwiYiI6bnVsbCwibSI
      6bnVsbCwibCI6bnVsbCwiYnMiOm51bGwsIm51bGwiOm51bGwsImJvb2wiOm51bGwsInNzIjpudWxs
      LCJucyI6bnVsbH0sIlBLIjp7InMiOiJQVUJMSVNIIzc2Y2IxYjA1LWNiMWUtNGFkZi04NjNhLWIyY
      Tk0YTVlY2RjZiNGVUxMIzU5NyIsIm4iOm51bGwsImIiOm51bGwsIm0iOm51bGwsImwiOm51bGwsIm
      JzIjpudWxsLCJudWxsIjpudWxsLCJib29sIjpudWxsLCJzcyI6bnVsbCwibnMiOm51bGx9fSwiYWN
      0aXZlVmVyc2lvbkluZGV4IjoiQUNUSVZFX1ZFUlNJT05fMiIsInZlcnNpb24iOiJ2MSJ9
    vary: Accept-Encoding
    content-encoding: gzip
    Strict-Transport-Security: max-age=31536000; includeSubDomains
    CF-Cache-Status: DYNAMIC
    Expect-CT: max-age=604800, 
      report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
    Server: cloudflare
    CF-RAY: 6879473d0d6f1851-EWR
  3. Include the token string in the pageToken query parameter of another request to the endpoint.

    The following example shows the pageToken query parameter with a token string value.

    https://[toast-api-hostname]/config/v2/discounts?pageToken=Yzp7Imxhc3RUeXBlIjoiT
      WVudUl0ZW0iLCJsYXN0RXZhbHVhdGVkS2V5Ijp7IkFjdGl2ZVZlcnNpb25QSyI6eyJzIjoiUFVCTEl
      TSCM3NmNiMWIwNS1jYjFlLTRhZGYtODYzYS1iMmE5NGE1ZWNkY2YjTWVudUl0ZW0iLCJuIjpudWxsL
      CJiIjpudWxsLCJtIjpudWxsLCJsIjpudWxsLCJzcyI6bnVsbCwibnMiOm51bGwsImJzIjpudWxsLCJ
      udWxsIjpudWxsLCJib29sIjpudWxsfSwiU0siOnsicyI6Ik1lbnVJdGVtIzhhYzViNGU1LTRkOWMtN
      GNmNy1hZDE4LTBjZDg0ZmI3ZjhjZSIsIm4iOm51bGwsImIiOm51bGwsIm0iOm51bGwsImwiOm51bGw
      sInNzIjpudWxsLCJucyI6bnVsbCwiYnMiOm51bGwsIm51bGwiOm51bGwsImJvb2wiOm51bGx9LCJBY
      3RpdmVWZXJzaW9uMiI6eyJzIjoiOGFjNWI0ZTUtNGQ5Yy00Y2Y3LWFkMTgtMGNkODRmYjdmOGNlIiw
      ibiI6bnVsbCwiYiI6bnVsbCwibSI6bnVsbCwibCI6bnVsbCwic3MiOm51bGwsIm5zIjpudWxsLCJic
      yI6bnVsbCwibnVsbCI6bnVsbCwiYm9vbCI6bnVsbH0sIlBLIjp7InMiOiJQVUJMSVNIIzc2Y2IxYjA
      1LWNiMWUtNGFkZi04NjNhLWIyYTk0YTVlY2RjZiNGVUxMIzU5NSIsIm4iOm51bGwsImIiOm51bGwsI
      m0iOm51bGwsImwiOm51bGwsInNzIjpudWxsLCJucyI6bnVsbCwiYnMiOm51bGwsIm51bGwiOm51bGw
      sImJvb2wiOm51bGx9fSwiYWN0aXZlVmVyc2lvbkluZGV4IjoiQUNUSVZFX1ZFUlNJT05fMiIsInZlc
      nNpb24iOiJ2MSJ9
  4. Repeat Step 2 and Step 3 until the response you receive does not include a Toast-Next-Page-Token header field.

    When the response does not include the Toast-Next-Page-Token header field, you have received all the data objects in the endpoint response.