Plant Catalog Management Guide | definitely

This guide walks you through managing the plant inventory catalog using the REST API endpoints.

1. Adding a New Plant

To add a plant item to the inventory catalog, send a POST request to /plant with the required metadata schema.

Request Payload (POST /v3/plant)

{
  "id": 10,
  "name": "Ficus Elastica (Rubber Tree)",
  "category": {
    "id": 1,
    "name": "Indoor Trees"
  },
  "photoUrls": [
    "https://assets.plantstore.dev/images/ficus-elastica-1.jpg",
    "https://assets.plantstore.dev/images/ficus-elastica-2.jpg"
  ],
  "tags": [
    {
      "id": 101,
      "name": "easy-care"
    },
    {
      "id": 102,
      "name": "bright-indirect-light"
    }
  ],
  "status": "available"
}

Code Example

curl -X POST "https://api.plantstore.dev/v3/plant" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <OAUTH2_TOKEN>" \
  -d '{
    "id": 10,
    "name": "Ficus Elastica",
    "photoUrls": ["https://assets.plantstore.dev/images/ficus.jpg"],
    "status": "available"
  }'

2. Searching & Filtering Plants

Search by Status

Retrieve all plants matching specific inventory statuses (available, pending, sold):

GET /v3/plant/findByStatus?status=available,pending HTTP/1.1
Host: api.plantstore.dev
Accept: application/json

Response Payload (200 OK)

[
  {
    "id": 10,
    "name": "Ficus Elastica (Rubber Tree)",
    "status": "available"
  },
  {
    "id": 12,
    "name": "Monstera Deliciosa",
    "status": "pending"
  }
]

Search by Tags

Find plants based on one or more category tags:

GET /v3/plant/findByTags?tags=easy-care,pet-friendly HTTP/1.1
Host: api.plantstore.dev
Accept: application/json

3. Uploading Plant Images

Attach high-resolution product photographs to an existing plant record via POST /plant/{plantId}/uploadImage:

Upload Image via multipart/form-data

curl -X POST "https://api.plantstore.dev/v3/plant/10/uploadImage" \
  -H "Authorization: Bearer <OAUTH2_TOKEN>" \
  -F "additionalMetadata=High-res product photo" \
  -F "file=@/path/to/ficus.jpg"

Response Payload

{
  "code": 200,
  "type": "SUCCESS",
  "message": "additionalMetadata: High-res product photo\nFile uploaded to https://assets.plantstore.dev/images/upload_10.jpg"
}

4. Updating & Deleting Plants

Update Existing Plant: PUT /plant (updates all plant attributes).
Update Status via Form Data: POST /plant/{plantId} (updates name and status via URL-encoded form data).
Delete Plant: DELETE /plant/{plantId} (requires valid api_key or write:plants scope).

Deleting a plant that has active pending orders will result in a 409 Conflict error. Ensure all orders are completed or cancelled prior to deleting plant inventory.