> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cocartapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limiting

> Control and prevent abuse from excessive calls.

<Note>
  Rate Limiting is only available with [CoCart Plus](https://cocartapi.com/pricing/).
</Note>

Popular stores can become the targets of malicious actors. One example of known abusive patterns is making many requests in a very short timeframe to try to overwhelm the store.

<Info>
  Rate limiting is opt-in and is intended for advanced merchants and platforms.
</Info>

## What it does?

Rate limiting is to prevent abuse on endpoints from excessive calls and performance degradation on the machine running the store.

Limiting is based on user ID for registered users (logged in) and IP address for guest users (unauthenticated requests).

It also offers standard support for running behind a proxy, load balancer, etc. This is also optional and is disabled by default.

The rate limiting uses a modified `wc_rate_limit` table with an additional remaining column for tracking the request count in any given request window.

## Limit information

A default maximum of 25 requests can be made within a 10-second time frame. These can be changed through `cocart_api_rate_limit_options` filter.

## Methods restricted by Rate Limiting

`POST`, `PUT`, `PATCH`, and `DELETE`

## Enable Rate Limiting

Developers can enable rate limiting using the `cocart_api_rate_limit_options` filter.

```php theme={"system"}
add_filter( 'cocart_api_rate_limit_options', function() {
	return [
		'enabled' => RateLimits::ENABLED, // enables/disables Rate Limiting. Default: false
		'proxy_support' => RateLimits::PROXY_SUPPORT, // enables/disables Proxy support. Default: false
		'limit' => RateLimits::LIMIT, // limit of request per timeframe. Default: 25
		'seconds' => RateLimits::SECONDS, // timeframe in seconds. Default: 10
	];
} );
```

## Supporting Proxies

Like any mechanism that restricts usage to counter potential abuse of an API, this is a sensitive feature that should be used carefully.

In a scenario where a store is behind another service layer (a proxy, load balancer, etc.), the developer should enable standard proxy support through the

Otherwise rate limiting might be wrongly triggered and group-limit requests.

## Proxy support

For the `proxy_support` option to work properly, service layers (load balancer, cache service, CDNs, etc.) must be passing the originating IP supported through standard IP forwarding headers, namely:

* `X_REAL_IP`|`CLIENT_IP` *Custom popular implementations that simplify obtaining the origin IP for the request*
* `X_FORWARDED_FOR` *De-facto standard header for identifying the originating IP, [Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)*
* `X_FORWARDED` *[Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [RFC 7239](https://datatracker.ietf.org/doc/html/rfc7239)*

<Info>
  This is disabled by default.
</Info>

## Limit usage information observability

Current limit information can be observed via custom response headers:

* `RateLimit-Limit` *Maximum requests per time frame.*
* `RateLimit-Remaining` *Requests available during current time frame.*
* `RateLimit-Reset` *Unix timestamp of next time frame reset.*
* `RateLimit-Retry-After` *Seconds until requests are unblocked again. Only shown when the limit is reached.*

### Response headers example

```http theme={"system"}
RateLimit-Limit: 5
RateLimit-Remaining: 0
RateLimit-Reset: 1654880642
RateLimit-Retry-After: 28
```

## Tracking Abuses

Developers can use the `cocart_api_rate_limit_exceeded` action to track and handle instances of API abuse:

```php theme={"system"}
add_action(
    'cocart_api_rate_limit_exceeded',
    function ( $offending_ip ) { /* Custom tracking implementation */ }
);
```

## Testing Guide

### Without proxy support

1. Enable Rate Limiting by using the [options filter](#enable-rate-limiting).
2. In a short window, keep making API requests.
3. Check that RateLimit-xxx headers change on each request.
4. Check that once you've hit the limit, an error response is returned. You can modify the limits using the [options filter](#enable-rate-limiting) to make it easier to test.

### With proxy support, do the same as before and

1. Enable proxy support
2. Make your requests with one of the following request headers containing always the same IP address:
   * X-Real-IP or Client-IP
   * [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
   * [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded)

### User Facing Testing

1. Enable Rate Limiting by using the [options filter](#enable-rate-limiting).
2. Try to apply a coupon or access `/wp-json/cocart/v2/coupon` beyond current limits (currently 25 requests under 10 seconds)
3. Ensure you get presented with an error "Too many requests. Please wait xx seconds before trying again."