Copied!
Natakahii v1.0
https://up.openjournaltheme.com/api/v1

API Reference

Complete reference for the Natakahii REST API. All endpoints accept and return JSON. This page also documents the Firebase Google sign-in exchange and the cargo webhook flow that keeps ecommerce orders synchronized with Natakahii Cargo.

Authentication — Endpoints marked with a red AUTH chip require a valid JWT token. Include it as Authorization: Bearer <token> in every authenticated request.
Media Storage — All uploaded files (images, videos, logos) are stored in Backblaze B2 cloud storage and served via CDN. File URLs in responses use the format https://cdn.natakahii.com/path/file.ext.
How It Works

Firebase Google Sign-In

  1. The frontend authenticates the customer with Firebase Google Auth.
  2. Firebase returns an ID token to the frontend.
  3. The frontend sends that token to /api/v1/auth/google.
  4. Natakahii verifies the Firebase token, links or creates the user, and returns the regular Natakahii JWT.
How It Works

Marketplace to Cargo Fulfillment

  1. The customer checks out with delivery_method=natakahii_cargo and shipping details.
  2. The order stays pending until the payment webhook marks it as paid.
  3. Natakahii splits the paid order by vendor and sends dropoff requests to the cargo system.
  4. Cargo reports receiving, QC, shipment, and delivery events back to /api/v1/integrations/cargo/events.
  5. Natakahii updates order cargo statuses automatically and creates refunds when QC fails.

Authentication

Endpoints for email/password authentication, Firebase Google sign-in, token management, and password recovery.

Request Body application/json
Parameter Type Required Rules Description
name string Yes max:255 Full name of the user.
email string Yes email|unique:users Valid email address. Must be unique.
password string Yes min:8|mixed_case|numbers Password with uppercase, lowercase and numbers.
phone string Optional max:20 Phone number (optional).
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "SecurePass123",
    "phone": "+255700000000"
}'
Responses
200 OK
JSON 
{
    "message": "Registration initiated. Please check your email for OTP verification.",
    "email": "[email protected]"
}
422

Validation failed

JSON 
{
    "message": "The email has already been taken.",
    "errors": {
        "email": [
            "The email has already been taken."
        ]
    }
}
Request Body application/json
Parameter Type Required Rules Description
email string Yes email Email used during registration.
otp string Yes size:6 Six-digit OTP code received via email.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/verify-registration" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "otp": "123456"
}'
Responses
201 OK
JSON 
{
    "message": "Registration successful.",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_type": "bearer",
    "expires_in": 3600
}
400

Invalid or expired OTP

JSON 
{
    "message": "Invalid or expired OTP."
}
404

Registration data expired

JSON 
{
    "message": "Registration data not found or expired. Please register again."
}
Request Body application/json
Parameter Type Required Rules Description
email string Yes email Registered email address.
password string Yes — Account password.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123"
}'
Responses
200 OK
JSON 
{
    "message": "Login successful.",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_type": "bearer",
    "expires_in": 3600
}
401

Invalid credentials

JSON 
{
    "message": "Invalid email or password."
}
403

Account blocked

JSON 
{
    "message": "Your account has been blocked. Please contact support."
}
Request Body application/json
Parameter Type Required Rules Description
id_token string Yes — Firebase ID token returned by the frontend after Google sign-in with Firebase Auth.
How It Works
  1. The frontend signs the user in with Firebase Google Auth and reads the Firebase ID token.
  2. Send that Firebase ID token to this endpoint instead of a Google access token or profile payload.
  3. Natakahii verifies the Firebase token, links or creates a customer account, and returns the platform JWT for authenticated API calls.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/google" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id_token": "FIREBASE_ID_TOKEN"
}'
Responses
200 OK
JSON 
{
    "message": "Login successful.",
    "user": {
        "id": 1,
        "name": "Jane Customer",
        "email": "[email protected]",
        "profile_photo": "https://lh3.googleusercontent.com/a/sample-photo",
        "status": "active",
        "roles": [
            {
                "id": 1,
                "name": "customer"
            }
        ]
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_type": "bearer",
    "expires_in": 3600
}
401

Invalid Firebase token

JSON 
{
    "message": "Invalid Google sign-in token."
}
403

Account blocked

JSON 
{
    "message": "Your account has been blocked. Please contact support."
}
409

Email linked to another Google account

JSON 
{
    "message": "This email is already linked to another Google account."
}
422

Verified email required

JSON 
{
    "message": "A verified Google email address is required."
}
503

Server-side Google sign-in unavailable

JSON 
{
    "message": "Google sign-in is temporarily unavailable on the server."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/logout" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Successfully logged out."
}
401

Unauthenticated

JSON 
{
    "message": "Unauthenticated."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_type": "bearer",
    "expires_in": 3600
}
401

Unauthenticated

JSON 
{
    "message": "Unauthenticated."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/auth/me" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+1234567890",
        "profile_photo": "https://cdn.natakahii.com/users/avatars/abc123.jpg",
        "status": "active",
        "roles": [
            {
                "id": 1,
                "name": "customer"
            }
        ]
    }
}
401

Unauthenticated

JSON 
{
    "message": "Unauthenticated."
}
Request Body application/json
Parameter Type Required Rules Description
email string Yes email|exists:users Registered email address.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]"
}'
Responses
200 OK
JSON 
{
    "message": "Password reset OTP sent to your email."
}
422

Validation failed

JSON 
{
    "message": "The selected email is invalid.",
    "errors": {
        "email": [
            "The selected email is invalid."
        ]
    }
}
Request Body application/json
Parameter Type Required Rules Description
email string Yes email|exists:users Registered email address.
otp string Yes size:6 Six-digit OTP code from email.
password string Yes min:8|mixed_case|numbers|confirmed New password.
password_confirmation string Yes — Must match password field.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "otp": "123456",
    "password": "SecurePass123",
    "password_confirmation": "SecurePass123"
}'
Responses
200 OK
JSON 
{
    "message": "Password reset successful. You can now login with your new password."
}
400

Invalid or expired OTP

JSON 
{
    "message": "Invalid or expired OTP."
}
Request Body application/json
Parameter Type Required Rules Description
email string Yes email Email to resend OTP to.
type string Yes in:registration,password_reset,email_verification OTP purpose type.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/auth/resend-otp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "type": "value"
}'
Responses
200 OK
JSON 
{
    "message": "OTP resent successfully."
}
429

Too many requests

JSON 
{
    "message": "Please wait before requesting a new OTP."
}

User Profile

Manage the authenticated user's profile and profile photo. Photos are stored in Backblaze B2 and served via CDN.

Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/vendor-application/status" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "status": "pending",
    "application": {
        "id": 1,
        "business_name": "My Store",
        "status": "pending",
        "submitted_at": "2026-02-08T10: 00: 00Z"
    }
}
401

Unauthenticated

JSON 
{
    "message": "Unauthenticated."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
business_name string Yes max:255 Business/shop name.
business_description string Yes — Description of the business.
business_address string Yes — Business physical address.
business_phone string Yes max:20 Business contact phone.
business_email string Yes email Business contact email.
tax_id string Optional max:50 Tax ID number (optional).
documents array Optional — Array of document file uploads.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/vendor-application" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "business_name": "John Doe",
    "business_description": "value",
    "business_address": "Mlimani City",
    "business_phone": "+255700000000",
    "business_email": "[email protected]",
    "tax_id": "value",
    "documents": []
}'
Responses
201 OK
JSON 
{
    "message": "Vendor application submitted successfully.",
    "application": {
        "id": 1,
        "business_name": "My Store",
        "status": "pending"
    }
}
422

Validation failed

JSON 
{
    "message": "The business name field is required."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
name string Optional max:255 Updated display name.
phone string Optional max:20 Updated phone number.
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/profile" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "phone": "+255700000000"
}'
Responses
200 OK
JSON 
{
    "message": "Profile updated.",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+255700000000",
        "profile_photo": "https://cdn.natakahii.com/users/avatars/abc123.jpg",
        "status": "active",
        "roles": [
            "customer"
        ]
    }
}
401

Unauthenticated

JSON 
{
    "message": "Unauthenticated."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
photo file Yes image|max:5120 Profile photo image (max 5MB). Accepts JPEG, PNG, GIF, WebP.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/profile/photo" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "photo=@/path/to/photo.jpg"
Responses
200 OK
JSON 
{
    "message": "Profile photo updated.",
    "user": {
        "id": 1,
        "name": "John Doe",
        "profile_photo": "https://cdn.natakahii.com/users/avatars/abc123.jpg"
    }
}
422

Validation failed

JSON 
{
    "message": "The photo field must be an image.",
    "errors": {
        "photo": [
            "The photo field must be an image."
        ]
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X DELETE \
  "https://up.openjournaltheme.com/api/v1/profile/photo" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Profile photo removed.",
    "user": {
        "id": 1,
        "name": "John Doe",
        "profile_photo": null
    }
}
401

Unauthenticated

JSON 
{
    "message": "Unauthenticated."
}

Catalog

Public product catalog browsing. No authentication required.

cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/categories" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "categories": [
        {
            "id": 1,
            "name": "Electronics",
            "slug": "electronics",
            "children": [
                {
                    "id": 2,
                    "name": "Phones"
                }
            ],
            "products_count": 45
        }
    ]
}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/categories/{category}/filters" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "category": {
        "id": 1,
        "name": "Electronics"
    },
    "filters": [
        {
            "id": 1,
            "name": "Color",
            "values": [
                {
                    "id": 1,
                    "value": "Red"
                }
            ]
        }
    ]
}
404

Category not found

JSON 
{
    "message": "Not found."
}
Request Body application/json
Parameter Type Required Rules Description
category_id integer Optional — Filter by category.
vendor_id integer Optional — Filter by vendor.
search string Optional — Search by name or description.
min_price number Optional — Minimum price filter.
max_price number Optional — Maximum price filter.
sort_by string Optional in:created_at,price,name Sort field. Default: created_at.
sort_dir string Optional in:asc,desc Sort direction. Default: desc.
per_page integer Optional — Items per page. Default: 15.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/products" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "products": [
        {
            "id": 1,
            "name": "Wireless Earbuds",
            "price": "29999.00",
            "image": "https://cdn.natakahii.com/products/1/earbuds.jpg",
            "vendor": {
                "shop_name": "TechShop",
                "logo": "https://cdn.natakahii.com/vendors/logos/techshop.png"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 15,
        "total": 68
    }
}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/products/{product}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "product": {
        "id": 1,
        "name": "Wireless Earbuds",
        "price": "29999.00",
        "images": [
            "https://cdn.natakahii.com/products/1/earbuds.jpg"
        ],
        "variants": [],
        "reviews_count": 12,
        "reviews_avg_rating": "4.50"
    },
    "recent_reviews": []
}
404

Product not found

JSON 
{
    "message": "Not found."
}
Request Body application/json
Parameter Type Required Rules Description
attribute_value_ids string Yes — Comma-separated attribute value IDs.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/products/{product}/variants/resolve?attribute_value_ids=1,4,7" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "variant": {
        "id": 1,
        "sku": "WE-BLK-M",
        "price": "29999.00",
        "stock": 50
    }
}
404

No matching variant

JSON 
{
    "message": "No matching variant found for the selected attributes."
}
Request Body application/json
Parameter Type Required Rules Description
search string Optional — Search by shop name or description.
per_page integer Optional — Items per page. Default: 15.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/vendors" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "vendors": [
        {
            "id": 1,
            "shop_name": "TechShop",
            "logo": "https://cdn.natakahii.com/vendors/logos/techshop.png",
            "products_count": 45
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 2,
        "per_page": 15,
        "total": 20
    }
}

Vendor

Vendor store management. Requires authentication and vendor role.

Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
shop_name string Yes max:255 Store display name.
shop_slug string Yes alpha_dash|unique:vendors URL-friendly store slug.
description string Optional — Store description.
logo file Optional image|max:2048 Store logo image.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/vendor/profile" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "shop_name=value" \
  -F "shop_slug=value" \
  -F "description=value" \
  -F "logo=@/path/to/logo.jpg"
Responses
201 OK
JSON 
{
    "message": "Vendor profile created. Awaiting approval.",
    "vendor": {
        "id": 1,
        "shop_name": "My Store",
        "logo": "https://cdn.natakahii.com/vendors/logos/my-store.png",
        "status": "pending"
    }
}
422

Validation failed

JSON 
{
    "message": "The shop slug has already been taken."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
category_id integer Yes exists:categories,id Product category.
name string Yes max:255 Product name.
description string Optional — Product description.
price number Yes numeric|min:0 Base price.
discount_price number Optional numeric|min:0 Discounted price.
stock integer Yes integer|min:0 Available stock.
images[] file Optional image|max:2048 Product images (multiple).
variants array Optional — Array of variant objects with sku, price, stock, attributes.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/vendor/products" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "category_id=1" \
  -F "name=value" \
  -F "description=value" \
  -F "price=100.00" \
  -F "discount_price=100.00" \
  -F "stock=1" \
  -F "images[]=@/path/to/images.jpg" \
  -F "variants=[]"
Responses
201 OK
JSON 
{
    "message": "Product created successfully.",
    "product": {
        "id": 1,
        "name": "Wireless Earbuds",
        "slug": "wireless-earbuds-abc123",
        "images": [
            "https://cdn.natakahii.com/products/1/earbuds-1.jpg",
            "https://cdn.natakahii.com/products/1/earbuds-2.jpg"
        ]
    }
}
403

Vendor not approved

JSON 
{
    "message": "Your vendor account must be approved before listing products."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/vendor/dropoffs" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "dropoffs": [
        {
            "id": 1,
            "status": "pending",
            "order_id": 10
        }
    ]
}
404

No vendor profile

JSON 
{
    "message": "No vendor profile found."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
order_id integer Yes exists:orders,id Order to drop off.
fulfillment_center_id integer Yes exists:fulfillment_centers,id Target fulfillment center.
notes string Optional — Additional notes.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/vendor/dropoffs" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "order_id": 1,
    "fulfillment_center_id": 1,
    "notes": "value"
}'
Responses
201 OK
JSON 
{
    "message": "Dropoff registered.",
    "dropoff": {
        "id": 1,
        "status": "pending"
    }
}
404

No vendor profile

JSON 
{
    "message": "No vendor profile found."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
file file Yes max:51200 Image or video file (max 50MB).
type string Yes in:image,video Media type.
title string Optional max:255 Media title.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/vendor/products/{product}/media" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/file.jpg" \
  -F "type=value" \
  -F "title=value"
Responses
201 OK
JSON 
{
    "message": "Media uploaded.",
    "media": {
        "id": 1,
        "type": "image",
        "file_path": "https://cdn.natakahii.com/media/1/photo.jpg"
    }
}
403

Not product owner

JSON 
{
    "message": "You do not own this product."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
title string Optional max:255 Updated media title.
display_order integer Optional min:0 Display order for sorting.
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/vendor/media/{media}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "value",
    "display_order": 1
}'
Responses
200 OK
JSON 
{
    "message": "Media updated.",
    "media": {
        "id": 1,
        "title": "Product Photo",
        "display_order": 1
    }
}
404

Media not found

JSON 
{
    "message": "Media not found."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X DELETE \
  "https://up.openjournaltheme.com/api/v1/vendor/media/{media}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Media deleted."
}
404

Media not found

JSON 
{
    "message": "Media not found."
}

Cart, Wishlist & Alerts

Shopping cart management, wishlists and price/stock alerts. Requires authentication.

Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/cart" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "cart": {
        "id": 1,
        "items": [
            {
                "id": 1,
                "product_id": 5,
                "quantity": 2,
                "price": "29999.00"
            }
        ]
    }
}
401

Unauthenticated

JSON 
{
    "message": "Unauthenticated."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
product_id integer Yes exists:products,id Product to add.
quantity integer Yes min:1 Quantity to add.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/cart/items" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "product_id": 1,
    "quantity": 1
}'
Responses
200 OK
JSON 
{
    "message": "Item added to cart.",
    "cart": {
        "id": 1,
        "items": []
    }
}
422

Validation failed

JSON 
{
    "message": "The selected product id is invalid."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
per_page integer Optional — Items per page.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/wishlists" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "wishlists": [
        {
            "id": 1,
            "product_id": 5,
            "product": {
                "name": "Earbuds",
                "image": "https://cdn.natakahii.com/products/5/earbuds.jpg"
            }
        }
    ],
    "meta": {
        "total": 3
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
product_id integer Yes exists:products,id Product to toggle.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/wishlists/toggle" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "product_id": 1
}'
Responses
201 OK
JSON 
{
    "message": "Product added to wishlist.",
    "wishlisted": true
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
product_id integer Yes exists:products,id Product to watch.
type string Yes in:price_drop,back_in_stock Alert type.
target_price number Optional required_if:type,price_drop Target price for price_drop alerts.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/alerts" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "product_id": 1,
    "type": "value",
    "target_price": 100
}'
Responses
201 OK
JSON 
{
    "message": "Alert created.",
    "alert": {
        "id": 1,
        "type": "price_drop",
        "target_price": "20000.00"
    }
}

Checkout & Payments

Convert carts to orders, process payments, request shipping quotes, and trigger Natakahii Cargo fulfillment after successful payment.

Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
delivery_method string Optional max:50 Delivery option chosen by the customer. Use `natakahii_cargo` for marketplace-to-cargo fulfillment.
shipping_provider string Optional max:100 Shipping provider label. Usually filled automatically from a selected quote.
shipping_service_level string Optional max:50 Requested service level such as `standard` or `express`.
shipping_amount number Optional min:0 Quoted shipping amount if you are not passing `shipping_quote_id`.
shipping_currency string Optional size:3 Currency code for shipping charges, such as `TZS`.
shipping_contact_name string Optional required when delivery_method=natakahii_cargo|max:255 Recipient contact name. Required for Natakahii Cargo orders.
shipping_contact_phone string Optional required when delivery_method=natakahii_cargo|max:30 Recipient phone number. Required for Natakahii Cargo orders.
shipping_address string Optional required when delivery_method=natakahii_cargo Delivery street or address details. Required for Natakahii Cargo orders.
shipping_city string Optional required when delivery_method=natakahii_cargo|max:100 Destination city. Required for Natakahii Cargo orders.
shipping_region string Optional max:100 Destination region/state if available.
pickup_center_code string Optional max:50 Preferred Natakahii Cargo office or fulfillment center code for vendor dropoff intake.
shipping_quote_id integer Optional exists:shipping_quotes,id Previously selected shipping quote to bind to this order.
How It Works
  1. Optionally request shipping quotes first, then pass `shipping_quote_id` at checkout to lock the quote into the order.
  2. When `delivery_method` is `natakahii_cargo`, include recipient contact and destination details so cargo can fulfill the shipment after payment.
  3. The order is created in `pending` payment state. Natakahii Cargo orders are stored with `cargo_fulfillment_status=awaiting_payment` and `cargo_sync_status=pending` until payment succeeds.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/checkout" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "delivery_method": "natakahii_cargo",
    "shipping_provider": "NatakaHii Cargo",
    "shipping_service_level": "standard",
    "shipping_amount": 100,
    "shipping_currency": "TZS",
    "shipping_contact_name": "John Doe",
    "shipping_contact_phone": "+255700000000",
    "shipping_address": "Mlimani City",
    "shipping_city": "Dar es Salaam",
    "shipping_region": "Dar es Salaam",
    "pickup_center_code": "DSM-CARGO-01",
    "shipping_quote_id": 1
}'
Responses
201 OK
JSON 
{
    "message": "Order placed successfully.",
    "order": {
        "id": 1,
        "order_number": "NTK-20260208-ABC123",
        "total_amount": "59998.00",
        "status": "pending",
        "payment_status": "pending",
        "delivery_method": "natakahii_cargo",
        "shipping_provider": "NatakaHii Cargo",
        "shipping_amount": "5000.00",
        "cargo_fulfillment_status": "awaiting_payment",
        "cargo_sync_status": "pending"
    }
}
422

Empty cart

JSON 
{
    "message": "Your cart is empty."
}
422

Selected quote not found

JSON 
{
    "message": "Selected shipping quote was not found."
}
422

Selected quote expired

JSON 
{
    "message": "Selected shipping quote has expired."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
order_id integer Yes exists:orders,id Order to pay for.
payment_method string Yes in:mpesa,card,bank_transfer Payment method.
How It Works
  1. Call this endpoint after checkout to create the pending payment record.
  2. Complete the payment through the provider flow in your frontend or provider UI.
  3. Once the payment webhook reports success, Natakahii marks the order as paid and automatically sends Natakahii Cargo orders to the cargo system vendor by vendor.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/payments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "order_id": 1,
    "payment_method": "value"
}'
Responses
201 OK
JSON 
{
    "message": "Payment initiated. Complete payment using the provided details.",
    "payment": {
        "id": 1,
        "amount": "59998.00",
        "status": "pending"
    }
}
422

Already paid

JSON 
{
    "message": "This order has already been paid."
}
Headers
HeaderValue
X-Webhook-Signature HMAC_SHA256(raw_body, provider_webhook_secret)
Request Body application/json
Parameter Type Required Rules Description
transaction_id string Yes — Provider transaction ID.
status string Yes — Payment status from the provider. `success` and `completed` are treated as paid.
How It Works
  1. The payment provider signs the raw webhook body and sends the signature in `X-Webhook-Signature`.
  2. Natakahii maps provider statuses into local payment states and updates the related order.
  3. If the order uses `natakahii_cargo`, a successful payment triggers creation and syncing of vendor-specific cargo dropoff requests.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/payments/webhook/{provider}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Webhook-Signature: HMAC_SHA256(raw_body, provider_webhook_secret)" \
  -d '{
    "transaction_id": "TXN-12345",
    "status": "success"
}'
Responses
200 OK
JSON 
{
    "message": "Webhook processed."
}
400

Invalid payload

JSON 
{
    "message": "Invalid webhook payload."
}
401

Invalid webhook signature

JSON 
{
    "message": "Invalid webhook signature."
}
404

Payment not found

JSON 
{
    "message": "Payment not found."
}
Request Body application/json
Parameter Type Required Rules Description
destination_address string Yes — Delivery destination address.
weight_kg number Yes min:0.1 Total weight in kilograms.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/shipping/quotes" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "destination_address": "Mlimani City",
    "weight_kg": 100
}'
Responses
200 OK
JSON 
{
    "message": "Shipping quotes generated.",
    "quotes": [
        {
            "provider": "NatakaHii Cargo",
            "service_level": "standard",
            "price": "5000.00",
            "estimated_days": 5
        }
    ]
}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/shipping/quotes/{quote}/select" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "message": "Shipping quote selected."
}
422

Quote expired

JSON 
{
    "message": "This quote has expired. Please request new quotes."
}

Social Commerce

Social engagement features: likes, shares, follows, views, and not-interested markers.

cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/products/{product}/view" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "message": "View recorded."
}
Request Body application/json
Parameter Type Required Rules Description
platform string Optional max:50 Share platform (e.g. whatsapp, facebook).
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/products/{product}/shares" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "platform": "value"
}'
Responses
200 OK
JSON 
{
    "message": "Share recorded.",
    "shares_count": 15
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/products/{product}/likes" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Product liked.",
    "likes_count": 42
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X DELETE \
  "https://up.openjournaltheme.com/api/v1/products/{product}/likes" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Product unliked.",
    "likes_count": 41
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/vendors/{vendor}/follow" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Now following TechShop.",
    "followers_count": 150
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X DELETE \
  "https://up.openjournaltheme.com/api/v1/vendors/{vendor}/follow" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Unfollowed TechShop.",
    "followers_count": 149
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/me/following/vendors" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "vendors": [
        {
            "id": 1,
            "shop_name": "TechShop"
        }
    ],
    "meta": {
        "total": 5
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/products/{product}/not-interested" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Product marked as not interested."
}

Media & Video

Product media management and video commerce feed.

cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/products/{product}/media" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "media": [
        {
            "id": 1,
            "type": "image",
            "file_path": "https://cdn.natakahii.com/media/1/photo.jpg",
            "mime_type": "image/jpeg"
        }
    ]
}
Request Body application/json
Parameter Type Required Rules Description
per_page integer Optional — Items per page.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/videos/feed" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Responses
200 OK
JSON 
{
    "videos": [
        {
            "id": 1,
            "type": "video",
            "file_path": "https://cdn.natakahii.com/media/1/demo.mp4",
            "mime_type": "video/mp4",
            "product": {
                "name": "Earbuds"
            }
        }
    ],
    "meta": {
        "total": 25
    }
}

AI Shopping Assistant

AI-powered shopping assistant for product recommendations and conversations.

Request Body application/json
Parameter Type Required Rules Description
message string Yes max:2000 Your question or message.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/ai/ask" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "message": "value"
}'
Responses
200 OK
JSON 
{
    "reply": "Thank you for your question! Try browsing our product catalog."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/ai/conversations" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "conversations": [
        {
            "id": 1,
            "title": "Shopping help",
            "messages_count": 5
        }
    ]
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
title string Optional max:255 Conversation title.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/ai/conversations" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "value"
}'
Responses
201 OK
JSON 
{
    "message": "Conversation created.",
    "conversation": {
        "id": 1,
        "title": "Shopping help"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/ai/conversations/{conversation}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "conversation": {
        "id": 1,
        "title": "Shopping help",
        "messages": [
            {
                "id": 1,
                "role": "user",
                "content": "Hello"
            },
            {
                "id": 2,
                "role": "assistant",
                "content": "Hi! How can I help?"
            }
        ]
    }
}
403

Not your conversation

JSON 
{
    "message": "Forbidden."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
message string Yes max:2000 Your message.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/ai/conversations/{conversation}/messages" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "message": "value"
}'
Responses
200 OK
JSON 
{
    "reply": {
        "role": "assistant",
        "content": "Check back soon for personalized recommendations."
    }
}
403

Not your conversation

JSON 
{
    "message": "Forbidden."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/ai/recommendations" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "recommendations": [
        {
            "id": 1,
            "name": "Wireless Earbuds",
            "price": "29999.00"
        }
    ]
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
product_id integer Optional exists:products,id Related product.
event_type string Yes max:50 Event type (click, add_to_cart, purchase).
metadata object Optional — Additional event data.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/ai/recommendation-events" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "product_id": 1,
    "event_type": "value",
    "metadata": {}
}'
Responses
200 OK
JSON 
{
    "message": "Event tracked."
}

Cargo & Shipping

Fulfillment centers, dropoff management, cargo shipments, delivery runs, and tracking for both standalone cargo work and marketplace-originated Natakahii Cargo orders.

Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/cargo/fulfillment-centers" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "fulfillment_centers": [
        {
            "id": 1,
            "name": "Dar es Salaam Hub",
            "city": "Dar es Salaam"
        }
    ]
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional in:pending,received,qc_in_progress,qc_passed,qc_failed Filter by dropoff status.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/cargo/dropoffs" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "dropoffs": [
        {
            "id": 1,
            "status": "pending",
            "order_id": 10,
            "vendor": {
                "shop_name": "TechShop"
            }
        }
    ],
    "meta": {
        "total": 25
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
fulfillment_center_id integer Yes exists:fulfillment_centers,id Receiving center.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/cargo/dropoffs/{dropoff}/receive" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "fulfillment_center_id": 1
}'
Responses
200 OK
JSON 
{
    "message": "Dropoff received.",
    "dropoff": {
        "status": "received"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
items array Yes — Array of items with product_id and quantity.
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/cargo/dropoffs/{dropoff}/items" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "items": []
}'
Responses
200 OK
JSON 
{
    "message": "Dropoff items updated.",
    "dropoff": {
        "id": 1,
        "items": []
    }
}
422

Invalid items

JSON 
{
    "message": "Invalid item data provided."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/cargo/dropoffs/{dropoff}/qc/start" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "QC started.",
    "dropoff": {
        "status": "qc_in_progress"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
passed boolean Yes — Whether QC passed.
notes string Optional — QC notes.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/cargo/dropoffs/{dropoff}/qc/complete" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "passed": true,
    "notes": "value"
}'
Responses
200 OK
JSON 
{
    "message": "QC completed.",
    "dropoff": {
        "status": "qc_passed"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
order_id integer Yes exists:orders,id Order to ship.
destination_address string Yes — Delivery address.
recipient_name string Yes max:255 Recipient name.
recipient_phone string Optional max:20 Recipient phone.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/cargo/shipments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "order_id": 1,
    "destination_address": "Mlimani City",
    "recipient_name": "John Doe",
    "recipient_phone": "+255700000000"
}'
Responses
201 OK
JSON 
{
    "message": "Shipment created.",
    "shipment": {
        "tracking_number": "NTK-SHP-ABC123",
        "status": "pending"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/shipments/{shipment}/tracking" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "shipment": {
        "tracking_number": "NTK-SHP-ABC123",
        "status": "in_transit"
    },
    "tracking_events": [
        {
            "event": "shipped",
            "location": "Dar es Salaam"
        }
    ]
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/cargo/shipments/{shipment}/mark-delivered" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Shipment marked as delivered."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/cargo/my/delivery-runs" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "delivery_runs": [
        {
            "id": 1,
            "status": "dispatched",
            "scheduled_date": "2026-02-10"
        }
    ]
}

Integrations

Internal webhook and system-to-system endpoints that keep Natakahii synchronized with external services such as Natakahii Cargo.

Headers
HeaderValue
X-Cargo-Signature HMAC_SHA256(raw_body, CARGO_WEBHOOK_SECRET)
Request Body application/json
Parameter Type Required Rules Description
event string Yes max:100 Cargo event name. Supported values include `dropoff.received`, `dropoff.qc_passed`, `dropoff.qc_failed`, `shipment.created`, and `shipment.delivered`.
data.external_order_id integer Yes — Natakahii order ID stored in cargo as the external order reference.
data.external_vendor_id integer Optional — Vendor ID for vendor-specific dropoff updates.
data.cargo_dropoff_id string Optional — Cargo-side dropoff identifier.
data.cargo_shipment_id string Optional — Cargo-side shipment identifier, when available.
data.tracking_number string Optional — Tracking number assigned by Natakahii Cargo.
data.status string Optional — Cargo status label supplied by the sender.
data.notes string Optional — Operational notes such as QC results or delivery comments.
How It Works
  1. Natakahii Cargo signs the raw JSON body with the shared cargo webhook secret and sends the signature in `X-Cargo-Signature`.
  2. Natakahii resolves the local order and vendor dropoff using the external IDs in the webhook payload.
  3. Order-level cargo statuses are recalculated from the vendor dropoff states after each event.
  4. When QC fails, Natakahii automatically creates refund payment records for the affected vendor items, and refunds shipping if the whole order fails.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/integrations/cargo/events" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Cargo-Signature: HMAC_SHA256(raw_body, CARGO_WEBHOOK_SECRET)" \
  -d '{
    "event": "dropoff.received",
    "data": {
        "external_order_id": 1,
        "external_vendor_id": 1,
        "cargo_dropoff_id": "value",
        "cargo_shipment_id": "value",
        "tracking_number": "NTK-SHP-ABC123",
        "status": "success",
        "notes": "value"
    }
}'
Responses
200 OK
JSON 
{
    "message": "Cargo event processed.",
    "order_id": 12
}
401

Invalid cargo webhook signature

JSON 
{
    "message": "Invalid cargo webhook signature."
}
404

Order not found

JSON 
{
    "message": "No query results for model [App\\Models\\Order] 12"
}
422

Validation failed

JSON 
{
    "message": "The data.external order id field is required."
}

Messaging & Disputes

User-to-user messaging and order dispute management.

Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
receiver_id integer Yes exists:users,id User to message.
subject string Optional max:255 Conversation subject.
message string Yes — First message content.
order_id integer Optional exists:orders,id Related order (optional).
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/messages/conversations" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "receiver_id": 1,
    "subject": "value",
    "message": "value",
    "order_id": 1
}'
Responses
201 OK
JSON 
{
    "message": "Conversation started.",
    "conversation": {
        "id": 1,
        "subject": "Order question"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
order_id integer Yes exists:orders,id Order to dispute.
reason string Yes max:255 Dispute reason.
description string Yes — Detailed description of the issue.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/disputes" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "order_id": 1,
    "reason": "value",
    "description": "value"
}'
Responses
201 OK
JSON 
{
    "message": "Dispute filed.",
    "dispute": {
        "id": 1,
        "status": "open",
        "reason": "Wrong item received"
    }
}
422

Active dispute exists

JSON 
{
    "message": "An active dispute already exists for this order."
}

Analytics & Notifications

Vendor analytics dashboard and user notifications.

Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/analytics/vendor/overview" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "analytics": {
        "total_products": 25,
        "active_products": 20,
        "total_orders": 150,
        "total_revenue": 450000
    }
}
404

No vendor profile

JSON 
{
    "message": "No vendor profile found."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
per_page integer Optional — Items per page.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/notifications" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "notifications": [],
    "unread_count": 3,
    "meta": {
        "total": 15
    }
}

Admin

Administrative endpoints for platform management. Requires admin role.

Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/dashboard" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Dashboard statistics retrieved.",
    "data": {
        "total_users": 150,
        "active_users": 142,
        "total_vendors": 25,
        "total_products": 340,
        "total_orders": 1200,
        "total_revenue": 58750
    }
}
403

Forbidden

JSON 
{
    "message": "Forbidden. Admin access required."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional in:active,blocked Filter by status.
role string Optional — Filter by role name.
search string Optional — Search by name or email.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/users" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Users retrieved.",
    "data": {
        "data": [
            {
                "id": 1,
                "name": "John Doe",
                "status": "active"
            }
        ],
        "total": 150
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/users/{user}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]",
        "status": "active",
        "roles": [
            "customer",
            "vendor"
        ]
    }
}
404

User not found

JSON 
{
    "message": "User not found."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/roles" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "roles": [
        {
            "id": 1,
            "name": "customer"
        },
        {
            "id": 2,
            "name": "vendor"
        },
        {
            "id": 3,
            "name": "admin"
        }
    ]
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Yes in:active,blocked New status.
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/admin/users/{user}/status" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "success"
}'
Responses
200 OK
JSON 
{
    "message": "User status updated to blocked."
}
403

Cannot change own status

JSON 
{
    "message": "You cannot change your own status."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
role string Yes exists:roles,name Role name.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/users/{user}/assign-role" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "role": "value"
}'
Responses
200 OK
JSON 
{
    "message": "Role 'vendor' assigned to John Doe."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
role string Yes exists:roles,name Role name to revoke.
cURL Example
BASH 
curl -X DELETE \
  "https://up.openjournaltheme.com/api/v1/admin/users/{user}/revoke-role" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Role 'vendor' revoked from John Doe."
}
403

Cannot revoke own admin role

JSON 
{
    "message": "You cannot revoke your own admin role."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional — Filter by vendor status.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/vendors" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "vendors": [
        {
            "id": 1,
            "shop_name": "TechShop",
            "logo": "https://cdn.natakahii.com/vendors/logos/techshop.png",
            "status": "approved"
        }
    ],
    "meta": {
        "total": 25
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Yes in:approved,suspended New vendor status.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/vendors/{vendor}/verification/review" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "success"
}'
Responses
200 OK
JSON 
{
    "message": "Vendor approved."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional in:pending,approved,rejected Filter by application status.
search string Optional — Search by business name or applicant name.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/vendor-applications" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "applications": [
        {
            "id": 1,
            "business_name": "My Store",
            "status": "pending",
            "user": {
                "name": "John Doe"
            }
        }
    ],
    "meta": {
        "total": 10
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/vendor-applications/{application}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "application": {
        "id": 1,
        "business_name": "My Store",
        "business_description": "We sell electronics",
        "status": "pending",
        "documents": []
    }
}
404

Application not found

JSON 
{
    "message": "Application not found."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Yes in:approved,rejected New status.
notes string Optional — Admin notes about the decision.
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/admin/vendor-applications/{application}/status" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "success",
    "notes": "value"
}'
Responses
200 OK
JSON 
{
    "message": "Application approved. Vendor account created.",
    "application": {
        "id": 1,
        "status": "approved"
    }
}
422

Invalid status transition

JSON 
{
    "message": "Cannot change status of processed application."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/categories" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "categories": [
        {
            "id": 1,
            "name": "Electronics",
            "slug": "electronics",
            "is_active": true,
            "sort_order": 1,
            "children": [],
            "products_count": 45
        }
    ]
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
name string Yes max:255 Category name.
slug string Optional max:255|unique:categories URL-friendly slug (auto-generated if not provided).
parent_id integer Optional exists:categories,id Parent category ID for subcategories.
is_active boolean Optional — Active status. Default: true.
sort_order integer Optional min:0 Display order. Auto-assigned if not provided.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/categories" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "slug": "value",
    "parent_id": 1,
    "is_active": true,
    "sort_order": 1
}'
Responses
201 OK
JSON 
{
    "message": "Category created successfully",
    "category": {
        "id": 1,
        "name": "Electronics",
        "slug": "electronics",
        "is_active": true,
        "sort_order": 1
    }
}
422

Validation failed

JSON 
{
    "message": "The name field is required.",
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
name string Optional max:255 Updated category name.
slug string Optional max:255|unique:categories Updated slug.
parent_id integer Optional exists:categories,id Updated parent category.
is_active boolean Optional — Updated active status.
sort_order integer Optional min:0 Updated sort order.
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/admin/categories/{category}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "slug": "value",
    "parent_id": 1,
    "is_active": true,
    "sort_order": 1
}'
Responses
200 OK
JSON 
{
    "message": "Category updated successfully",
    "category": {
        "id": 1,
        "name": "Electronics & Gadgets",
        "slug": "electronics-gadgets"
    }
}
404

Category not found

JSON 
{
    "message": "Not found."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X DELETE \
  "https://up.openjournaltheme.com/api/v1/admin/categories/{category}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Category deleted successfully"
}
422

Cannot delete

JSON 
{
    "message": "Cannot delete category with existing products"
}
404

Category not found

JSON 
{
    "message": "Not found."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/admin/categories/{category}/toggle-status" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Category status updated successfully",
    "category": {
        "id": 1,
        "is_active": false
    }
}
404

Category not found

JSON 
{
    "message": "Not found."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional — Filter by product status.
vendor_id integer Optional — Filter by vendor.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/products" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "products": [],
    "meta": {
        "total": 340
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Yes in:active,draft,out_of_stock New product status.
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/admin/products/{product}/moderation" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "success"
}'
Responses
200 OK
JSON 
{
    "message": "Product status changed to active."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional — Filter by order status.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/orders" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "orders": [],
    "meta": {
        "total": 1200
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional — Filter by payment status.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/payments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "payments": [],
    "meta": {
        "total": 980
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/escrow/orders/{order}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "order": {
        "id": 1,
        "order_number": "NTK-20260208-ABC123"
    },
    "escrow": {
        "amount": "59998.00",
        "status": "held",
        "held_since": "2026-02-08T10: 00: 00Z"
    }
}
404

Order not found

JSON 
{
    "message": "Order not found."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional — Filter by shipment status.
tracking_number string Optional — Search by tracking number.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/shipments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "shipments": [
        {
            "id": 1,
            "tracking_number": "NTK-SHP-ABC123",
            "status": "in_transit"
        }
    ],
    "meta": {
        "total": 50
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/cargo/shipments/{shipment}/inspections" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "inspections": [
        {
            "id": 1,
            "status": "passed",
            "inspected_at": "2026-02-08T12: 00: 00Z",
            "notes": "All items verified"
        }
    ]
}
404

Shipment not found

JSON 
{
    "message": "Shipment not found."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
order_id integer Yes exists:orders,id Order to refund.
amount number Yes min:0.01 Refund amount.
reason string Yes — Refund reason.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/refunds" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "order_id": 1,
    "amount": 100,
    "reason": "value"
}'
Responses
201 OK
JSON 
{
    "message": "Refund processed."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Yes in:resolved,rejected Resolution status.
resolution string Yes — Resolution description.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/disputes/{dispute}/resolve" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "success",
    "resolution": "value"
}'
Responses
200 OK
JSON 
{
    "message": "Dispute resolved."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
delivery_agent_id integer Yes exists:users,id Assigned delivery agent.
scheduled_date string Yes date Scheduled delivery date (Y-m-d).
vehicle_info string Optional max:255 Vehicle information.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/delivery-runs" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "delivery_agent_id": 1,
    "scheduled_date": "value",
    "vehicle_info": "value"
}'
Responses
201 OK
JSON 
{
    "message": "Delivery run created.",
    "delivery_run": {
        "id": 1,
        "status": "scheduled"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
shipment_ids array Yes — Array of shipment IDs to assign.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/delivery-runs/{run}/shipments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "shipment_ids": []
}'
Responses
200 OK
JSON 
{
    "message": "Shipments assigned to delivery run.",
    "assigned_count": 3
}
422

Invalid shipments

JSON 
{
    "message": "Some shipments are not available for assignment."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/delivery-runs/{run}/dispatch" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Delivery run dispatched.",
    "delivery_run": {
        "id": 1,
        "status": "dispatched"
    }
}
422

Already dispatched

JSON 
{
    "message": "Delivery run is already dispatched."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional in:open,pending,resolved,closed Filter by ticket status.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/support/tickets" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "tickets": [
        {
            "id": 1,
            "subject": "Order Issue",
            "status": "open"
        }
    ],
    "meta": {
        "total": 25
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/analytics/overview" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "analytics": {
        "users": 150,
        "vendors": 20,
        "products": 340,
        "orders_total": 1200,
        "revenue_total": 58750
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
status string Optional in:open,resolved,rejected Filter by dispute status.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/disputes" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "disputes": [
        {
            "id": 1,
            "status": "open",
            "reason": "Wrong item"
        }
    ],
    "meta": {
        "total": 10
    }
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/reports" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "reports": {
        "total_users": 150,
        "total_vendors": 25,
        "total_products": 340,
        "total_orders": 1200,
        "total_revenue": 58750
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
action string Yes in:warn,suspend,remove,ignore Action to take on the report.
notes string Optional — Admin notes about the action.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/reports/{report}/action" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "action": "value",
    "notes": "value"
}'
Responses
200 OK
JSON 
{
    "message": "Report action taken.",
    "action": "warn"
}
404

Report not found

JSON 
{
    "message": "Report not found."
}

Super Admin

Super admin only endpoints. Manage admin accounts, settings, fees, plans, and audit logs.

Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/super/admins" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "admins": [
        {
            "id": 1,
            "name": "Super Admin",
            "email": "[email protected]"
        }
    ]
}
403

Super admin required

JSON 
{
    "message": "Forbidden. Super admin access required."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
name string Yes max:255 Admin name.
email string Yes email|unique:users Admin email.
password string Yes min:8 Admin password.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/super/admins" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "SecurePass123"
}'
Responses
201 OK
JSON 
{
    "message": "Admin account created.",
    "admin": {
        "id": 2,
        "name": "New Admin"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
name string Optional max:255 Updated admin name.
email string Optional email|unique:users Updated admin email.
password string Optional min:8 New password (if changing).
cURL Example
BASH 
curl -X PATCH \
  "https://up.openjournaltheme.com/api/v1/admin/super/admins/{user}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "SecurePass123"
}'
Responses
200 OK
JSON 
{
    "message": "Admin account updated.",
    "admin": {
        "id": 2,
        "name": "Updated Name"
    }
}
404

Admin not found

JSON 
{
    "message": "Admin not found."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X DELETE \
  "https://up.openjournaltheme.com/api/v1/admin/super/admins/{user}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "message": "Admin account deleted."
}
403

Cannot delete self

JSON 
{
    "message": "Cannot delete your own account."
}
Headers
HeaderValue
Authorization Bearer {token}
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/super/settings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "settings": {
        "general": [
            {
                "key": "platform_name",
                "value": "NatakaHii"
            }
        ]
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
settings array Yes — Array of {key, value, group} objects.
cURL Example
BASH 
curl -X PUT \
  "https://up.openjournaltheme.com/api/v1/admin/super/settings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "settings": []
}'
Responses
200 OK
JSON 
{
    "message": "Settings updated."
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
name string Yes max:255 Rule name.
type string Yes in:percentage,flat Fee type.
value number Yes min:0 Fee value.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/super/platform-fees" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "type": "value",
    "value": 100
}'
Responses
201 OK
JSON 
{
    "message": "Platform fee rule created.",
    "rule": {
        "name": "Commission",
        "type": "percentage",
        "value": "10.00"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
name string Yes max:255 Plan name.
price number Yes min:0 Plan price.
billing_cycle string Yes in:monthly,yearly Billing cycle.
features array Optional — Array of feature strings.
cURL Example
BASH 
curl -X POST \
  "https://up.openjournaltheme.com/api/v1/admin/super/subscription-plans" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "price": 100,
    "billing_cycle": "value",
    "features": []
}'
Responses
201 OK
JSON 
{
    "message": "Subscription plan created.",
    "plan": {
        "name": "Premium",
        "price": "50000.00"
    }
}
Headers
HeaderValue
Authorization Bearer {token}
Request Body application/json
Parameter Type Required Rules Description
action string Optional — Filter by action type.
user_id integer Optional — Filter by user.
cURL Example
BASH 
curl -X GET \
  "https://up.openjournaltheme.com/api/v1/admin/super/audit-logs" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
Responses
200 OK
JSON 
{
    "audit_logs": [
        {
            "id": 1,
            "action": "user.blocked",
            "user": {
                "name": "Admin"
            }
        }
    ],
    "meta": {
        "total": 500
    }
}