specification: API Commons Rate Limits
specificationVersion: '0.1'
provider: Lightspeed Commerce
providerId: lightspeed
name: Lightspeed Commerce API Rate Limits
description: >-
  Every Lightspeed product line rate-limits differently, and two of them scale the limit with how much
  hardware the retailer runs. X-Series uses a 5-minute window sized at 300 x registers + 50; R-Series
  uses a leaky bucket whose size and drip rate grow per register, with per-request costs that vary by
  query parameter and nested relation. Both publish runtime headers, which is what an agent actually
  needs.
created: '2026-06-13'
modified: '2026-08-27'
generated: '2026-08-27'
method: searched
source: >-
  https://x-series-api.lightspeedhq.com/docs/rate_limiting,
  https://x-series-api.lightspeedhq.com/docs/authorization#rate-limiting,
  https://developers.lightspeedhq.com/retail/introduction/ratelimits/,
  https://developers.lightspeedhq.com/ecom/introduction/rate-limiting/
sources:
- https://x-series-api.lightspeedhq.com/docs/rate_limiting
- https://x-series-api.lightspeedhq.com/docs/authorization
- https://developers.lightspeedhq.com/retail/introduction/ratelimits/
- https://developers.lightspeedhq.com/ecom/introduction/rate-limiting/
headers:
  x_series: [X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After]
  x_series_token_endpoint: [X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset]
  r_series: [X-LS-Api-Bucket-Level, X-LS-Api-Burst-Level, X-LS-Api-Drip-Rate, X-LS-Api-Request-Cost, Retry-After]
responseCodes:
  throttled: 429
limit_count: 6
limits:
- name: X-Series API requests, per retailer per application
  product: Retail X-Series
  scope: per-application-per-retailer
  metric: requests
  limit: 350
  window: 300
  timeFrame: 5 minutes
  formula: 300 * <number of registers> + 50
  note: >-
    350 is the value for a single-register store, which is Lightspeed's own worked example. The limit
    grows with register count, so a retailer's API headroom is a function of the hardware they bought.
  algorithm: fixed 5-minute window
- name: X-Series API requests, per retailer for all users
  product: Retail X-Series
  scope: per-retailer-all-users
  metric: requests
  limit: 350
  window: 300
  timeFrame: 5 minutes
  formula: 300 * <number of registers> + 50
  note: >-
    A separate bucket from the application bucket, deliberately, so an integration cannot rate-limit
    in-store staff mid-transaction and vice versa.
- name: X-Series token endpoint
  product: Retail X-Series
  scope: per-application
  metric: requests
  limit: null
  window: null
  endpoint: https://{domain_prefix}.retail.lightspeed.app/api/1.0/token
  headers: [X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset]
  note: >-
    Rate limited independently of the rest of the API, and the limit is discoverable only at runtime:
    Lightspeed's documentation shows example headers (limit 10) but states explicitly that "all of
    these values are subject to change", so no numeric limit is recorded here. X-RateLimit-Reset is a
    Unix epoch second. Lightspeed's guidance is to use an access token until it expires (86400s)
    rather than re-minting it, which avoids this limit entirely.
- name: R-Series leaky bucket, base
  product: Retail R-Series
  scope: per-account
  metric: requests
  limit: 90
  burst: 90
  rate: 1
  timeFrame: per second drip
  algorithm: leaky bucket
  note: 90-request bucket draining at 1 request per second.
- name: R-Series leaky bucket, per additional register
  product: Retail R-Series
  scope: per-account
  metric: requests
  limit: 10
  rate: 0.5
  timeFrame: per second drip
  algorithm: leaky bucket increment
  note: >-
    Each register beyond the first adds 10 to the bucket and 0.5 drips/second. Lightspeed's worked
    example: 3 registers gives a 110-request bucket at 2 drips/second.
- name: R-Series burst limiter
  product: Retail R-Series
  scope: per-account
  metric: requests
  limit: null
  window: 1
  timeFrame: 1 second
  algorithm: fixed 1-second window
  note: >-
    A secondary limiter on top of the leaky bucket. Lightspeed documents the window (1 second) but not
    the threshold, so no number is recorded. Exceeding it returns 429 with the message "burst rate
    limit exceeded"; wait at least one second before retrying. Current usage is readable at runtime via
    X-LS-Api-Burst-Level.
request_costs:
  r_series:
    base: 1 drip per request
    query_parameters: additional cost, varies by parameter
    nested_relations: 0.5 drips per nested entity on POST/PUT
    header: X-LS-Api-Request-Cost reports the cost of the request just made
error_bodies:
  x_series:
    status: 429
    body: '{"error": "Too Many Requests", "message": "Rate limiting enforced"}'
    retry_after_format: RFC1123 HTTP-date, not seconds
  r_series:
    status: 429
    retry_after_format: seconds
undocumented:
- product: eCom C-Series
  note: >-
    Limits are stated to apply per API key and a rate-limiting page exists
    (https://developers.lightspeedhq.com/ecom/introduction/rate-limiting/), but no numeric limit,
    window or header set was captured in this pass. An Account Rate limits endpoint exists in the eCom
    endpoint list, which suggests the limit is readable at runtime rather than published.
- product: Restaurant K-Series
  note: No rate limits are documented and none are declared in the published OpenAPI.
best_practices:
- Queue API calls and defer on 429 rather than sleeping between every request (Lightspeed's own guidance).
- Read X-RateLimit-Remaining (X-Series) or X-LS-Api-Bucket-Level (R-Series) before deciding to send.
- On R-Series, prefer one call with nested relations over several separate calls — it costs fewer drips.