Deal Products API
Learn how to manage products associated with deals in AchieveApex using the REST API.
Overview
The Deal Products API allows you to manage products associated with deals in your organization. You can add, update, and remove products from deals, as well as apply discounts and taxes.
Base Endpoint
/deal-products
Deal Product Object
The deal product object contains information about a product associated with a deal.
Deal Product Object
{
"id": 501,
"quantity": "2",
"price": "10000.00",
"description": "Enterprise license",
"discount_type": "percentage",
"discount_amount": null,
"discount_percentage": "10",
"tax_percentage": "7",
"total_amount_with_tax": "19260.00",
"total_amount_without_tax": "18000.00",
"product_id": 601,
"deal_id": 123,
"organization_id": 456,
"name": "Software License",
"sku": "SL-001",
"created_at": "2023-01-01T00:00:00.000Z",
"updated_at": "2023-01-01T00:00:00.000Z",
"deleted_at": null,
"main_media_path": "/path/to/image.jpg"
}List Deal Products
Retrieve a list of products associated with a specific deal.
Request
GET /deal-products
curl -X GET https://api.achieveapex.com/deal-products \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": {
"deal_id": 123,
"organization_id": 456,
"$sort": { "created_at": -1 }
}
}'Response
{
"total": 2,
"limit": 10,
"skip": 0,
"data": [
{
"id": 501,
"quantity": "2",
"price": "10000.00",
"description": "Enterprise license",
"discount_type": "percentage",
"discount_amount": null,
"discount_percentage": "10",
"tax_percentage": "7",
"total_amount_with_tax": "19260.00",
"total_amount_without_tax": "18000.00",
"product_id": 601,
"deal_id": 123,
"organization_id": 456,
"name": "Software License",
"sku": "SL-001",
"created_at": "2023-01-01T00:00:00.000Z",
"updated_at": "2023-01-01T00:00:00.000Z"
},
{
"id": 502,
"quantity": "1",
"price": "5000.00",
"description": "Implementation service",
"discount_type": "none",
"discount_amount": null,
"discount_percentage": null,
"tax_percentage": "7",
"total_amount_with_tax": "5350.00",
"total_amount_without_tax": "5000.00",
"product_id": 602,
"deal_id": 123,
"organization_id": 456,
"name": "Implementation Service",
"sku": "SRV-001",
"created_at": "2023-01-01T00:00:00.000Z",
"updated_at": "2023-01-01T00:00:00.000Z"
}
]
}Query Parameters
| Parameter | Type | Description |
|---|---|---|
| deal_id | Number | ID of the deal to fetch products for (required) |
| organization_id | Number | ID of the organization (required) |
| $sort | Object | Sort criteria (e.g., { "created_at": -1 } for newest first) |
Get a Deal Product
Retrieve a single deal product by ID.
Request
GET /deal-products/:id curl -X GET https://api.achieveapex.com/deal-products/501 \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json"
Response
{
"id": 501,
"quantity": "2",
"price": "10000.00",
"description": "Enterprise license",
"discount_type": "percentage",
"discount_amount": null,
"discount_percentage": "10",
"tax_percentage": "7",
"total_amount_with_tax": "19260.00",
"total_amount_without_tax": "18000.00",
"product_id": 601,
"deal_id": 123,
"organization_id": 456,
"created_at": "2023-01-01T00:00:00.000Z",
"updated_at": "2023-01-01T00:00:00.000Z",
"deleted_at": null
}Add a Product to a Deal
Add a product to a deal with specific pricing, quantity, and discount information.
Request
POST /deal-products
curl -X POST https://api.achieveapex.com/deal-products \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deal_id": 123,
"organization_id": 456,
"product_id": 601,
"quantity": 2,
"price": 10000,
"description": "Enterprise license",
"discount_type": "percentage",
"discount_percentage": 10,
"tax_percentage": 7
}'Response
{
"id": 501,
"quantity": "2",
"price": "10000.00",
"description": "Enterprise license",
"discount_type": "percentage",
"discount_amount": null,
"discount_percentage": "10",
"tax_percentage": "7",
"total_amount_with_tax": "19260.00",
"total_amount_without_tax": "18000.00",
"product_id": 601,
"deal_id": 123,
"organization_id": 456,
"created_at": "2023-01-01T00:00:00.000Z",
"updated_at": "2023-01-01T00:00:00.000Z",
"deleted_at": null
}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| deal_id | Number | Yes | ID of the deal to add the product to |
| organization_id | Number | Yes | ID of the organization |
| product_id | Number | Yes | ID of the product to add |
| quantity | Number | Yes | Quantity of the product |
| price | Number | Yes | Price per unit |
| description | String | No | Description of the product in this deal |
| discount_type | String | No | Type of discount ('fixed', 'percentage', or 'none') |
| discount_amount | Number | No | Fixed discount amount (required if discount_type is 'fixed') |
| discount_percentage | Number | No | Percentage discount (required if discount_type is 'percentage') |
| tax_percentage | Number | No | Tax percentage to apply (default: 0) |
Update a Deal Product
Update an existing product's information in a deal.
Request
PATCH /deal-products/:id
curl -X PATCH https://api.achieveapex.com/deal-products/501 \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"quantity": 3,
"discount_type": "fixed",
"discount_amount": 5000,
"discount_percentage": null
}'Response
{
"id": 501,
"quantity": "3",
"price": "10000.00",
"description": "Enterprise license",
"discount_type": "fixed",
"discount_amount": "5000.00",
"discount_percentage": null,
"tax_percentage": "7",
"total_amount_with_tax": "26750.00",
"total_amount_without_tax": "25000.00",
"product_id": 601,
"deal_id": 123,
"organization_id": 456,
"created_at": "2023-01-01T00:00:00.000Z",
"updated_at": "2023-01-02T00:00:00.000Z",
"deleted_at": null
}When updating a deal product, the system automatically recalculates the total amounts based on the quantity, price, discount, and tax percentage.
Remove a Product from a Deal
Remove a product from a deal.
Request
DELETE /deal-products/:id curl -X DELETE https://api.achieveapex.com/deal-products/501 \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json"
Response
{
"id": 501,
"quantity": "3",
"price": "10000.00",
"description": "Enterprise license",
"discount_type": "fixed",
"discount_amount": "5000.00",
"discount_percentage": null,
"tax_percentage": "7",
"total_amount_with_tax": "26750.00",
"total_amount_without_tax": "25000.00",
"product_id": 601,
"deal_id": 123,
"organization_id": 456,
"created_at": "2023-01-01T00:00:00.000Z",
"updated_at": "2023-01-02T00:00:00.000Z",
"deleted_at": "2023-01-03T00:00:00.000Z"
}Error Handling
The Deal Products API returns standard HTTP status codes and error messages.
Error Response
{
"name": "NotFound",
"message": "No record found for id '999'",
"code": 404,
"className": "not-found"
}| Status Code | Description |
|---|---|
| 400 Bad Request | Invalid parameters or request |
| 401 Unauthorized | Missing or invalid authentication |
| 403 Forbidden | Not authorized to access this deal's products |
| 404 Not Found | Deal product not found |
| 500 Internal Server Error | Server error |
Related Documentation
For information on managing deals and products, see the Deals API and Products API documentation.
Report an issue with this documentation
Please log in to report issues with our documentation.