Versioning & rate limits

The stability commitment, deprecation headers and quota rules.

Stability commitment

You need to know your integration will not quietly break one morning. Our commitment:

A published field never changes its name or type. If it must change, it arrives in a new version.
Adding a field is not breaking. Your client must ignore fields it does not recognise — we will keep adding them.
Enum values are a closed set for this version. New values are added only with a new minor version and a changelog entry. If you meet a value you do not recognise (for example a status), do not ignore it; handle it with a safe default and log it.
When an endpoint is deprecated you get a Deprecation header and a changelog entry.
Any shutdown date is announced at least 6 months in advance via the Sunset header and the changelog.

Deprecation headers

A deprecated endpoint keeps working but tells you its status on every response (example):

HTTP

HTTP/1.1 200 OK
Deprecation: true
Link: </api/partner/v1/ornek-yeni-uc>; rel="successor-version",
      <https://developers.supergelsin.com/surumleme>; rel="deprecation"

Once a shutdown date exists, a Sunset header is added. The header is not sent before a date is decided — an invented date is worse than no date.

Log the Deprecation and Sunset headers in your integration. You will know months before an endpoint closes — even if you forget to read the changelog, your own code tells you.

Removals and deprecations

1.0.0 is the initial release; no endpoint is deprecated.

Rate limits

50 requests per 10 seconds, per service group and key. Counting is per group, not per endpoint. For the endpoints in each group and the other limits, see Service limits.

Order and store endpoints are in a different group from the catalogue; a large catalogue upload does not block order acceptance or closing the business. The connection notice (POST /reachability) and the courier's location are counted in their own groups too.

Every response that reaches authentication reports your remaining budget; you see it before you hit a 429:

HTTP

HTTP/1.1 200 OK
RateLimit-Limit: 50
RateLimit-Remaining: 47
RateLimit-Reset: 8          # seconds until the window resets

On overflow

HTTP/1.1 429 Too Many Requests
Retry-After: 6
RateLimit-Remaining: 0

{ "error": "too_many_requests", "reason": "rate_limit", ... }

Wait for Retry-After and add some jitter. A POS polling several businesses at once will rate-limit itself if every poll lands on the same second.

How to protect your budget

Poll the menu with If-None-Match; an unchanged menu returns a bodiless 304. A 304 response also consumes one request from the rate limit.
Use updatedSince when pulling orders; do not fetch the whole list every time.
Send updates in bulk: 100 items per request on the food menu, 1,000 on the Çarşı catalogue.
Set up webhooks. With push notifications there is no need to poll every second.
On Çarşı sync use updatedSince and the cursor — do not pull the entire catalogue from scratch every night.

Stability commitment

You need to know your integration will not quietly break one morning. Our commitment:

A published field never changes its name or type. If it must change, it arrives in a new version.

Adding a field is not breaking. Your client must ignore fields it does not recognise — we will keep adding them.

Enum values are a closed set for this version. New values are added only with a new minor version and a changelog entry. If you meet a value you do not recognise (for example a status), do not ignore it; handle it with a safe default and log it.

When an endpoint is deprecated you get a Deprecation header and a changelog entry.

Any shutdown date is announced at least 6 months in advance via the Sunset header and the changelog.

Deprecation headers

A deprecated endpoint keeps working but tells you its status on every response (example):

HTTP

HTTP/1.1 200 OK
Deprecation: true
Link: </api/partner/v1/ornek-yeni-uc>; rel="successor-version",
      <https://developers.supergelsin.com/surumleme>; rel="deprecation"

Once a shutdown date exists, a Sunset header is added. The header is not sent before a date is decided — an invented date is worse than no date.

Log the Deprecation and Sunset headers in your integration. You will know months before an endpoint closes — even if you forget to read the changelog, your own code tells you.

Rate limits

50 requests per 10 seconds, per service group and key. Counting is per group, not per endpoint. For the endpoints in each group and the other limits, see Service limits.

Every response that reaches authentication reports your remaining budget; you see it before you hit a 429:

HTTP

HTTP/1.1 200 OK
RateLimit-Limit: 50
RateLimit-Remaining: 47
RateLimit-Reset: 8          # seconds until the window resets

On overflow

HTTP/1.1 429 Too Many Requests
Retry-After: 6
RateLimit-Remaining: 0

{ "error": "too_many_requests", "reason": "rate_limit", ... }

Wait for Retry-After and add some jitter. A POS polling several businesses at once will rate-limit itself if every poll lands on the same second.

How to protect your budget

Poll the menu with If-None-Match; an unchanged menu returns a bodiless 304. A 304 response also consumes one request from the rate limit.

Use updatedSince when pulling orders; do not fetch the whole list every time.

Send updates in bulk: 100 items per request on the food menu, 1,000 on the Çarşı catalogue.

Set up webhooks. With push notifications there is no need to poll every second.

On Çarşı sync use updatedSince and the cursor — do not pull the entire catalogue from scratch every night.