Products API

Learn how to manage products in AchieveApex using the REST API.

Overview

The Products API allows you to manage products within your organization. You can list, retrieve, create, update, and delete products.

Base Endpoint

/products

Product Object

The product object contains information about a product in your catalog.

Product Object

{
  "id": 123,
  "name": "Premium Subscription",
  "description": "Annual premium subscription with all features included",
  "organization_id": 27,
  "status": "active",
  "type": "service",
  "price": 999.99,
  "parent_id": null,
  "sku": "PREM-SUB-12M",
  "stock_quantity": null,
  "is_variant": false,
  "product_category_id": 5,
  "created_at": "2025-03-15T10:45:20.391Z",
  "updated_at": "2025-03-15T10:45:20.391Z",
  "deleted_at": null
}

List Products

Retrieve a list of products in your organization with optional filtering and pagination.

Request

GET /products

curl -X GET https://api.achieveapex.com/products \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "organization_id": 27,
      "$limit": 10,
      "$skip": 0,
      "$sort": { "name": 1 }
    }
  }'

Response

{
  "total": 3,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "name": "Premium Subscription",
      "description": "Annual premium subscription with all features included",
      "organization_id": 27,
      "status": "active",
      "type": "service",
      "price": 999.99,
      "parent_id": null,
      "sku": "PREM-SUB-12M",
      "stock_quantity": null,
      "is_variant": false,
      "product_category_id": 5,
      "created_at": "2025-03-15T10:45:20.391Z",
      "updated_at": "2025-03-15T10:45:20.391Z",
      "deleted_at": null
    },
    {
      "id": 124,
      "name": "Standard Subscription",
      "description": "Annual standard subscription with basic features",
      "organization_id": 27,
      "status": "active",
      "type": "service",
      "price": 499.99,
      "parent_id": null,
      "sku": "STD-SUB-12M",
      "stock_quantity": null,
      "is_variant": false,
      "product_category_id": 5,
      "created_at": "2025-03-15T10:47:30.215Z",
      "updated_at": "2025-03-15T10:47:30.215Z",
      "deleted_at": null
    },
    {
      "id": 125,
      "name": "Hardware Protection Plan",
      "description": "Extended warranty and protection for hardware devices",
      "organization_id": 27,
      "status": "active",
      "type": "service",
      "price": 299.99,
      "parent_id": null,
      "sku": "HW-PROTECT-12M",
      "stock_quantity": null,
      "is_variant": false,
      "product_category_id": 6,
      "created_at": "2025-03-15T10:49:15.845Z",
      "updated_at": "2025-03-15T10:49:15.845Z",
      "deleted_at": null
    }
  ]
}

Query Parameters

Parameter	Type	Description
organization_id	Number	ID of the organization (required)
product_category_id	Number	Filter products by category ID
name	String	Filter products by name (supports partial matching)
status	String	Filter by status ('active' or 'inactive')
type	String	Filter by type ('product' or 'service')
price	Object	Filter by price range, e.g., `{ "$gte": 100, "$lte": 1000 }`
parent_id	Number	Filter by parent product ID
is_variant	Boolean	Filter for variant/non-variant products
$limit	Number	Number of products to return (default: 10)
$skip	Number	Number of products to skip (for pagination)
$sort	Object	Sort criteria (e.g., `{ "name": 1 }` for name ascending)

Get a Product

Retrieve a single product by ID.

Request

GET /products/:id

curl -X GET https://api.achieveapex.com/products/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "id": 123,
  "name": "Premium Subscription",
  "description": "Annual premium subscription with all features included",
  "organization_id": 27,
  "status": "active",
  "type": "service",
  "price": 999.99,
  "parent_id": null,
  "sku": "PREM-SUB-12M",
  "stock_quantity": null,
  "is_variant": false,
  "product_category_id": 5,
  "created_at": "2025-03-15T10:45:20.391Z",
  "updated_at": "2025-03-15T10:45:20.391Z",
  "deleted_at": null,
  "category": {
    "id": 5,
    "name": "Subscriptions"
  },
  "media": [
    {
      "id": 456,
      "file_name": "product-123-front.jpg",
      "file_type": "image/jpeg",
      "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-front.jpg",
      "position": 1
    }
  ],
  "variants": [],
  "parent": null
}

Create a Product

Create a new product in your organization.

Request

POST /products

curl -X POST https://api.achieveapex.com/products \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "Basic Subscription",
    "description": "Annual basic subscription for small teams",
    "status": "active",
    "type": "service",
    "price": 299.99,
    "sku": "BASIC-SUB-12M",
    "product_category_id": 5
  }'

Response

{
  "id": 126,
  "name": "Basic Subscription",
  "description": "Annual basic subscription for small teams",
  "organization_id": 27,
  "status": "active",
  "type": "service",
  "price": 299.99,
  "parent_id": null,
  "sku": "BASIC-SUB-12M",
  "stock_quantity": null,
  "is_variant": false,
  "product_category_id": 5,
  "created_at": "2025-03-22T16:15:44.782Z",
  "updated_at": "2025-03-22T16:15:44.782Z",
  "deleted_at": null
}

Update a Product

Update an existing product in your organization.

Request

PATCH /products/:id

curl -X PATCH https://api.achieveapex.com/products/126 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic Subscription Plus",
    "description": "Annual basic subscription with additional features",
    "price": 349.99
  }'

Response

{
  "id": 126,
  "name": "Basic Subscription Plus",
  "description": "Annual basic subscription with additional features",
  "organization_id": 27,
  "status": "active",
  "type": "service",
  "price": 349.99,
  "parent_id": null,
  "sku": "BASIC-SUB-12M",
  "stock_quantity": null,
  "is_variant": false,
  "product_category_id": 5,
  "created_at": "2025-03-22T16:15:44.782Z",
  "updated_at": "2025-03-22T16:20:12.345Z",
  "deleted_at": null
}

Create Product Variant

Create a variant of an existing product.

Request

POST /products

curl -X POST https://api.achieveapex.com/products \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "Premium Subscription (2-year)",
    "description": "2-year premium subscription with all features included",
    "status": "active",
    "type": "service",
    "price": 1799.99,
    "sku": "PREM-SUB-24M",
    "product_category_id": 5,
    "parent_id": 123,
    "is_variant": true
  }'

Response

{
  "id": 127,
  "name": "Premium Subscription (2-year)",
  "description": "2-year premium subscription with all features included",
  "organization_id": 27,
  "status": "active",
  "type": "service",
  "price": 1799.99,
  "parent_id": 123,
  "sku": "PREM-SUB-24M",
  "stock_quantity": null,
  "is_variant": true,
  "product_category_id": 5,
  "created_at": "2025-03-22T16:30:44.782Z",
  "updated_at": "2025-03-22T16:30:44.782Z",
  "deleted_at": null
}

Delete a Product

Delete a product from your organization.

Request

DELETE /products/:id

curl -X DELETE https://api.achieveapex.com/products/126 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "id": 126,
  "name": "Basic Subscription Plus",
  "description": "Annual basic subscription with additional features",
  "organization_id": 27,
  "status": "active",
  "type": "service",
  "price": 349.99,
  "parent_id": null,
  "sku": "BASIC-SUB-12M",
  "stock_quantity": null,
  "is_variant": false,
  "product_category_id": 5,
  "created_at": "2025-03-22T16:15:44.782Z",
  "updated_at": "2025-03-22T16:25:33.678Z",
  "deleted_at": "2025-03-22T16:25:33.678Z"
}

Note on Product Deletion

When a product is deleted, the system performs a soft delete by setting the deleted_at timestamp. The product will no longer appear in product listings but may still be referenced by existing deals or other records. If the product has variants, they will remain in the system but will no longer be accessible through the parent product.

Error Handling

The 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 organization's products
404 Not Found	Product not found
500 Internal Server Error	Server error

Products API

Overview

Product Object

List Products

Query Parameters

Get a Product

Create a Product

Update a Product

Create Product Variant

Delete a Product

Error Handling

Related Documentation

Report an issue with this documentation