◐OmniCart Docs
View as Markdown

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

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

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:

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:

# 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

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

Example: Delete Partner Offer

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:

{
  "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:

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:

{
  "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:

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

Example Request:

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:

{
  "id": "brand_01HQZX...",
  "deleted": true
}

Example Request:

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