Working with Products 🧪
Overview
The Catalog API provides a comprehensive system for managing three types of agricultural product data: Products (crop protection products), Items (general agricultural items), and Fertilizers. Organizations can create, update, and manage custom entries for all three categories. These registered products will be used in ag operations as inputs in work orders and work records.
Important: This API focuses on Custom Entries - products, items, and fertilizers created and managed by individual organizations for their specific needs.
Cardinality summary
- Product/Item/Fertilizer ➜ 1 Organization (each custom entry belongs to a specific organization)
- Product ➜ 1 Indication (product type/category)
- Item ➜ 1 Category (item classification)
- Fertilizer ➜ 1 Form (SOLID or LIQUID)
Catalog Structure
├── CP Products
│ └── Organization (1) - Each product belongs to exactly one organization
├── Items
│ └── Organization (1) - Each item belongs to exactly one organization
└── Fertilizers
└── Organization (1) - Each fertilizer belongs to exactly one organization
Key Concepts
| Concept | Description |
|---|---|
| CP Product | Crop protection product (herbicide, fungicide, insecticide, etc.) |
| Item | Agricultural item (supplies, equipment, etc.) |
| Fertilizer | Fertilizer with nutrient composition |
| Organization ID | UUID that identifies which organization owns the entry |
API Documentation
For complete API reference including request/response schemas, authentication, and interactive testing, visit:
📚 Catalog Cp Products API Documentation - Interactive API documentation with request/response examples
📚 Catalog Items API Documentation - Interactive API documentation with request/response examples
📚 Catalog Fertilizers API Documentation - Interactive API documentation with request/response examples
Available Endpoints
CP Products
Products CP represent crop protection products such as herbicides, fungicides, insecticides, and other agricultural chemicals.
| Method | Endpoint | Description |
|---|---|---|
| POST | /v2/catalog/products | Create a new custom product |
| GET | /v2/catalog/products/{product_id} | Get product by ID |
| PUT | /v2/catalog/products/{product_id} | Update product information |
| DELETE | /v2/catalog/products/{product_id} | Delete a custom product |
| POST | /v2/catalog/products/ids | Batch get products by IDs (up to 100) |
| GET | /v2/catalog/orgs/{org_id}/products | List organization's products with filtering |
Items
Items represent general agricultural items such as seeds, supplies, equipment, and other materials that aren't classified as products or fertilizers.
| Method | Endpoint | Description |
|---|---|---|
| POST | /v2/catalog/items | Create a new custom item |
| GET | /v2/catalog/items/{item_id} | Get item by ID |
| PUT | /v2/catalog/items/{item_id} | Update item information |
| DELETE | /v2/catalog/items/{item_id} | Delete a custom item |
| POST | /v2/catalog/items/ids | Batch get items by IDs (up to 100) |
| GET | /v2/catalog/orgs/{org_id}/items | List organization's items with filtering |
Fertilizers
Fertilizers represent nutrient products with specific chemical compositions used for plant nutrition.
| Method | Endpoint | Description |
|---|---|---|
| POST | /v2/catalog/fertilizers | Create a new custom fertilizer |
| GET | /v2/catalog/fertilizers/{fertilizer_id} | Get fertilizer by ID |
| PUT | /v2/catalog/fertilizers/{fertilizer_id} | Update fertilizer information |
| DELETE | /v2/catalog/fertilizers/{fertilizer_id} | Delete a custom fertilizer |
| POST | /v2/catalog/fertilizers/ids | Batch get fertilizers by IDs (up to 100) |
| GET | /v2/catalog/orgs/{org_id}/fertilizers | List organization's fertilizers with filtering |
Business Rules
Name Uniqueness
- Products: Each organization can only have one custom product/item/fertilizer with a given name. Names must be unique within an organization.
Organization Ownership
- All custom products, items, and fertilizers are permanently associated with a single organization via
org_id - Each organization maintains its own isolated catalog
Error Codes
| Code | Message | HTTP Status | When Triggered |
|---|---|---|---|
| ECPR001 | Product Duplicated Name/Org Error | 400 BAD_REQUEST | A product with the same name already exists for the organization |
| ECPR002 | Product Not Found Error | 404 NOT_FOUND | The requested product ID does not exist or has been deleted |
| ECPR003 | Invalid Attribute Error | 400 BAD_REQUEST | One or more product attributes contain invalid values |
| ECPR008 | Create Product ID Conflict | 409 CONFLICT | Product ID already exists in the system |
| ECIT001 | Item Not Found Error | 404 NOT_FOUND | The requested item ID does not exist or has been deleted |
| ECIT002 | Item Repeated Name Error | 400 BAD_REQUEST | An item with the same name already exists |
| ECIT003 | Item ID Conflict Error | 409 CONFLICT | Item ID already exists in the system |
| ECIT004 | Item Invalid Category Error | 400 BAD_REQUEST | The specified category is invalid or not supported |
| ECFR001 | Fertilizer Duplicated Name/Org Error | 409 CONFLICT | A fertilizer with the same name already exists for the organization |
| ECFR002 | Fertilizer Not Found Error | 404 NOT_FOUND | The requested fertilizer ID does not exist or has been deleted |
| ECFR003 | Invalid Attribute Error | 400 BAD_REQUEST | One or more fertilizer attributes contain invalid values |
| ECFR009 | Create Fertilizer ID Conflict | 409 CONFLICT | Fertilizer ID already exists in the system |
Typical Workflows
Basic Management Workflow
- Create Entry - Add a new custom product, item, or fertilizer to your organization's catalog
- Update Entry - Modify properties such as the name, and other details.
- Retrieve Entry - Get details.
- Delete Entry - Soft delete entries no longer in use
- Batch Retrieve - Get multiple entries by ID in a single request
Next Steps
- Learn how to use ag operations Ag Operations
- Explore Seeds for managing seed.