# Common Patterns

### Pagination

Most list endpoints support offset-based pagination with `offset` and `limit` query parameters.

**Query Parameters:**
- `offset` - Number of items to skip (default: 0)
- `limit` - Number of items to return (default: 50, max varies by endpoint)

**Example: Get Brands with Pagination**
```bash
# First page (items 0-49)
curl -X GET 'https://your-store.omnicart.cc/admin/brands?offset=0&limit=50' \
  -H 'Authorization: Bearer <admin_token>'

# Second page (items 50-99)
curl -X GET 'https://your-store.omnicart.cc/admin/brands?offset=50&limit=50' \
  -H 'Authorization: Bearer <admin_token>'
```

**Response Format:**
```json
{
  "brands": [...],
  "count": 237,
  "offset": 0,
  "limit": 50
}
```

**Pagination Calculation:**
```javascript
// Calculate pagination
const totalPages = Math.ceil(count / limit)
const currentPage = Math.floor(offset / limit) + 1
const hasNextPage = offset + limit < count
const hasPrevPage = offset > 0

// Next page
const nextOffset = offset + limit

// Previous page
const prevOffset = Math.max(0, offset - limit)
```

---

### Filtering

Many list endpoints support filtering by status, dates, or other entity properties.

**Example: Filter Brands by Status**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands?status=active' \
  -H 'Authorization: Bearer <admin_token>'
```

**Example: Filter Orders by Date Range**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/orders?created_at_gte=2026-01-01&created_at_lte=2026-01-31' \
  -H 'Authorization: Bearer <admin_token>'
```

**Common Filter Parameters:**
- `status` - Filter by status (active, inactive, pending, etc.)
- `created_at_gte` - Created after this date (ISO 8601)
- `created_at_lte` - Created before this date (ISO 8601)
- `updated_at_gte` - Updated after this date
- `updated_at_lte` - Updated before this date

**Multiple Filters:**
```bash
# Active brands updated in January 2026
curl -X GET 'https://your-store.omnicart.cc/admin/brands?status=active&updated_at_gte=2026-01-01&updated_at_lte=2026-01-31' \
  -H 'Authorization: Bearer <admin_token>'
```

---

### Searching

List endpoints often support full-text search via the `q` query parameter.

**Example: Search Brands by Name or Slug**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands?q=nike' \
  -H 'Authorization: Bearer <admin_token>'
```

**Search Behavior:**
- Case-insensitive
- Partial matching (wildcards)
- Searches multiple fields (name, slug, description, etc.)
- Can be combined with filters and pagination

**Example: Search + Filter + Pagination**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands?q=sport&status=active&offset=0&limit=20' \
  -H 'Authorization: Bearer <admin_token>'
```

---

### Sorting

Some endpoints support sorting via `order` or `sort` parameters.

**Example: Sort by Creation Date**
```bash
# Newest first (descending)
curl -X GET 'https://your-store.omnicart.cc/admin/orders?order=created_at:desc' \
  -H 'Authorization: Bearer <admin_token>'

# Oldest first (ascending)
curl -X GET 'https://your-store.omnicart.cc/admin/orders?order=created_at:asc' \
  -H 'Authorization: Bearer <admin_token>'
```

**Common Sort Fields:**
- `created_at` - Creation timestamp
- `updated_at` - Last update timestamp
- `name` - Alphabetical by name
- `status` - By status value
- `amount` - By monetary amount

---

### Relations & Field Selection

The API supports loading related entities via the `fields` query parameter.

**Example: Load Brands with Customer Avatars**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands?fields=+customer_avatars' \
  -H 'Authorization: Bearer <admin_token>'
```

**Example: Select Specific Fields Only**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands?fields=id,name,slug,status' \
  -H 'Authorization: Bearer <admin_token>'
```

**Note:** Relation loading behavior varies by endpoint. Check specific endpoint documentation for supported relations.

---