API Documentation

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header.

POST /v1/auth/token

Generate an access token using your API key and secret.

Parameter	Type	Required	Description
`api_key`	string	Required	Your API key
`api_secret`	string	Required	Your API secret

Request

curl -X POST https://api.kimidrop.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
  }'

Response

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
}

Products

Browse and manage products in the KimiDrop catalog. Retrieve product details, pricing, and inventory information.

GET /v1/products

List all available products with optional filtering and pagination.

Parameter	Type	Required	Description
`page`	integer	Optional	Page number (default: 1)
`limit`	integer	Optional	Items per page (default: 20, max: 100)
`category`	string	Optional	Filter by category

Request

curl -X GET "https://api.kimidrop.com/v1/products?page=1&limit=10&category=vitamins" \
  -H "Authorization: Bearer {access_token}"

Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "prod_123456",
        "name": "Multivitamin Gummies",
        "sku": "MVG-001",
        "category": "vitamins",
        "cost_price": 8.50,
        "suggested_retail": 24.99,
        "stock": 1250,
        "images": [
          "https://cdn.kimidrop.com/images/mvg-001-1.jpg"
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 523
    }
  }
}

GET /v1/products/{product_id}

Get detailed information for a specific product.

Request

curl -X GET https://api.kimidrop.com/v1/products/prod_123456 \
  -H "Authorization: Bearer {access_token}"

Orders

Create and manage orders. Orders are automatically processed and fulfilled by KimiDrop.

POST /v1/orders

Create a new order for fulfillment.

Parameter	Type	Required	Description
`external_id`	string	Required	Your internal order ID
`items`	array	Required	Array of order items
`shipping_address`	object	Required	Customer shipping address

Request

curl -X POST https://api.kimidrop.com/v1/orders \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ORDER-2024-001",
    "items": [
      {
        "product_id": "prod_123456",
        "quantity": 2
      }
    ],
    "shipping_address": {
      "name": "John Doe",
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US",
      "phone": "+1-555-0123"
    }
  }'

Response

{
  "success": true,
  "data": {
    "order_id": "ord_789012",
    "external_id": "ORDER-2024-001",
    "status": "pending",
    "total_cost": 17.00,
    "shipping_cost": 3.50,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

GET /v1/orders/{order_id}

Retrieve order details and current status.

Request

curl -X GET https://api.kimidrop.com/v1/orders/ord_789012 \
  -H "Authorization: Bearer {access_token}"

Shipping

Track shipments and manage delivery information for your orders.

GET /v1/shipping/track/{tracking_number}

Get real-time tracking information for a shipment.

Request

curl -X GET https://api.kimidrop.com/v1/shipping/track/1Z999AA10123456784 \
  -H "Authorization: Bearer {access_token}"

Response

{
  "success": true,
  "data": {
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "status": "in_transit",
    "estimated_delivery": "2024-01-20",
    "events": [
      {
        "timestamp": "2024-01-16T08:15:00Z",
        "location": "New York, NY",
        "description": "Package departed facility"
      },
      {
        "timestamp": "2024-01-15T14:30:00Z",
        "location": "New York, NY",
        "description": "Package received at facility"
      }
    ]
  }
}

GET /v1/shipping/rates

Get available shipping rates for a destination.

Request

curl -X GET "https://api.kimidrop.com/v1/shipping/rates?country=US&weight=0.5" \
  -H "Authorization: Bearer {access_token}"

Webhooks

Receive real-time notifications for order status changes, inventory updates, and other events.

POST /v1/webhooks

Register a new webhook endpoint.

Parameter	Type	Required	Description
`url`	string	Required	Your webhook endpoint URL
`events`	array	Required	Events to subscribe to

Request

curl -X POST https://api.kimidrop.com/v1/webhooks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-store.com/webhooks/kimidrop",
    "events": [
      "order.shipped",
      "order.delivered",
      "inventory.low_stock"
    ]
  }'

Response

{
  "success": true,
  "data": {
    "webhook_id": "whk_456789",
    "url": "https://your-store.com/webhooks/kimidrop",
    "events": [
      "order.shipped",
      "order.delivered",
      "inventory.low_stock"
    ],
    "secret": "whsec_abc123xyz789",
    "active": true
  }
}

POST Webhook Payload Example

Example payload sent to your webhook endpoint when an order is shipped.

Payload

{
  "event": "order.shipped",
  "timestamp": "2024-01-16T10:00:00Z",
  "data": {
    "order_id": "ord_789012",
    "external_id": "ORDER-2024-001",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "shipped_at": "2024-01-16T10:00:00Z"
  }
}