# Request & Response Formats

### Headers

**Required Headers:**
```
Content-Type: application/json
```

**Authentication Headers:**
```
Authorization: Bearer <token>
```

**Optional Headers:**
```
Accept: application/json
X-Request-ID: <unique_request_id>
```

---

### Request Body

POST, PATCH, and PUT requests typically accept JSON bodies.

**Example: Create Brand**
```bash
curl -X POST 'https://your-store.omnicart.cc/admin/brands' \
  -H 'Authorization: Bearer <admin_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Nike",
    "description": "Just Do It",
    "website": "https://example-brand.com",
    "status": "active",
    "metadata": {
      "founded": 1964,
      "headquarters": "Oregon, USA"
    }
  }'
```

**Example: Update Partner Profile**
```bash
curl -X PATCH 'https://your-store.omnicart.cc/store/partners/me' \
  -H 'x-publishable-api-key: pk_YOUR_PUBLISHABLE_KEY' \
  -H 'Authorization: Bearer <partner_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact_name": "Jane Doe",
    "phone": "+1-555-0200",
    "website": "https://example.com"
  }'
```

**Body Format:**
- Must be valid JSON
- Use camelCase for field names (some endpoints accept snake_case as well)
- Nested objects allowed
- Arrays allowed
- Date strings should be ISO 8601 format

---

### Query Parameters

GET and DELETE requests use query parameters for filtering, pagination, and configuration.

**Example with Multiple Query Params:**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands?status=active&q=sport&offset=0&limit=20&fields=id,name,slug' \
  -H 'Authorization: Bearer <admin_token>'
```

**URL Encoding:**
Query parameters must be URL-encoded:
```bash
# Space → %20 or +
curl -X GET 'https://your-store.omnicart.cc/admin/brands?q=nike%20air'

# Special characters
curl -X GET 'https://your-store.omnicart.cc/admin/brands?q=50%25%20off'
```

---

### Path Parameters

Dynamic route segments use `:parameter` notation.

**Example: Get Brand by ID**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands/brand_01HQZX...' \
  -H 'Authorization: Bearer <admin_token>'
```

**Example: Delete Partner Offer**
```bash
curl -X DELETE 'https://your-store.omnicart.cc/admin/partners/offers/offer_123' \
  -H 'Authorization: Bearer <admin_token>'
```

**Common Path Parameters:**
- `:id` - Resource ID (most common)
- `:code` - Referral code, promo code, etc.
- `:orderId` - Order identifier
- `:buttonId` - Button widget identifier
- `:page` - Page slug or identifier
- `:provider` - OAuth provider name

---

## Response Formats

### Success Responses

**Status Code:** 200 OK

**Single Resource:**
```json
{
  "brand": {
    "id": "brand_01HQZX...",
    "name": "Nike",
    "slug": "nike",
    "status": "active",
    "created_at": "2026-01-10T12:00:00Z",
    "updated_at": "2026-01-10T12:00:00Z"
  }
}
```

**Example Request:**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands/brand_01HQZX...' \
  -H 'Authorization: Bearer <admin_token>'
```

---

### Paginated Responses

**Status Code:** 200 OK

**List with Pagination:**
```json
{
  "brands": [
    {
      "id": "brand_01HQZX...",
      "name": "Nike",
      "slug": "nike"
    },
    {
      "id": "brand_01HQZY...",
      "name": "Adidas",
      "slug": "adidas"
    }
  ],
  "count": 237,
  "offset": 0,
  "limit": 50
}
```

**Response Fields:**
- `brands` (or other resource name) - Array of resources
- `count` - Total number of matching resources
- `offset` - Current offset (for pagination calculation)
- `limit` - Current limit (for pagination calculation)

---

### Created Resources

**Status Code:** 201 Created

**Response:**
```json
{
  "brand": {
    "id": "brand_01HQZX...",
    "name": "Nike",
    "slug": "nike",
    "status": "active",
    "created_at": "2026-01-12T10:30:00Z"
  }
}
```

**Example Request:**
```bash
curl -X POST 'https://your-store.omnicart.cc/admin/brands' \
  -H 'Authorization: Bearer <admin_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Nike",
    "description": "Just Do It"
  }'
```

---

### Deleted Resources

**Status Code:** 200 OK

**Response:**
```json
{
  "id": "brand_01HQZX...",
  "deleted": true
}
```

**Example Request:**
```bash
curl -X DELETE 'https://your-store.omnicart.cc/admin/brands/brand_01HQZX...' \
  -H 'Authorization: Bearer <admin_token>'
```

---