Products API

The Products API is designed to manage product data efficiently within an e-commerce environment. It supports product creation, modification, and deletion while handling pricing details, stock information, and recurrence settings.

The API ensures clear and consistent responses, including detailed error handling, to provide a smooth experience for developers.

Create a product¶

Endpoint

POST /v1/products/

This endpoint allows creating a new product in the system by sending a POST request with the product details — such as name, description, price, currency, stock, and whether it is physical (is_physical). If the operation is successful, it confirms the product’s creation and provides its unique id.

Request:

curl -X POST 'https://api.4geeks.io/v1/products/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Sample Product",
           "description": "This is a sample product",
           "price": 100.0,
           "currency": "CRC",
           "stock": 10,
           "is_physical": true
         }'

Response:

{
    "code": 201,
    "title": "Complete registration",
    "content": "The registration was successfully completed.",
    "type": "success",
    "data": {
        "id": "d36a4a5c-9fa9-4d55-b47f-4f1d50f2a180"
    }
}

Get all products¶

Endpoint

GET /v1/products/

This endpoint retrieves a list of all products with pagination support. You can specify the page number and the number of products per page using the page and page_size parameters.

Fields::

Parameter	Description	Type	Required
page	The page number to retrieve	integer	true
page_size	The number of products to display per page	integer	true
test	Indicates of the is in test mode (true for testing, false for production).	boolean	false

Request:

curl -X GET 'https://api.4geeks.io/v1/products/?page_size=1&page=1' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
    "count": 4,
    "current_page": 1,
    "total_pages": 4,
    "results": [
        {
            "id": "a232cccc-956a-44ca-a2e8-d763afddc89f",
            "name": "Sample Product 1",
            "short_description": null,
            "description": "This is a sample product",
            "stock": 0,
            "price": 100.0,
            "currency": "CRC",
            "is_physical": false,
            "bar_code": null,
            "sku": null,
            "recurrence": {
                "recurrence": "period",
                "duration_period": 6
            },
            "images": {
                "default": "",
                "aditional_images": []
            },
            "payment_link": false,
            "created_on": "2025-03-24T19:08:43.321357Z",
            "test": false,
            "taxes": [
                {"id": 1, "name": "iva", "value": 20.0},
                {"id": 3, "name": "iva", "value": 13.0}
            ]
        }
    ]
}

Get a specific product¶

Endpoint

GET /v1/products/{id}/

This endpoint get a specific product.

Fields::

Parameter	Description	Type	Required
test	Indicates of the is in test mode (true for testing, false for production).	boolean	false

Request:

curl -X GET 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
    "id": "f9b77185-a62e-4da9-a056-3c7b812ca334",
    "name": "Sample Product 2",
    "short_description": null,
    "description": "This is a sample product",
    "stock": 0,
    "price": 100.0,
    "currency": "CRC",
    "is_physical": false,
    "bar_code": null,
    "sku": null,
    "recurrence": {
        "recurrence": "period",
        "duration_period": 6
    },
    "images": {
        "default": "",
        "aditional_images": []
    },
    "payment_link": false,
    "created_on": "2025-03-25T08:50:15.732299Z",
    "test": true,
    "taxes": [
        {"id": 1, "name": "iva", "value": 20.0},
        {"id": 3, "name": "iva", "value": 13.0}
    ]
}

Update a product¶

Endpoint

PUT /v1/products/{id}/

This endpoint update a product.

Fields::

Parameter	Description	Type	Required
test	Indicates of the is in test mode (true for testing, false for production).	boolean	false

Request:

curl -X PUT 'https://api.4geeks.io/v1/products/{id}/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Updated Product Name",
           "description": "Updated description",
           "price": 120.0
         }'

Response:

{
    "code": 200,
    "title": "Updated product",
    "content": "The product was successfully updated.",
    "type": "success"
}

Delete a product¶

Endpoint

DELETE /v1/products/{id}/

This endpoint removes permanently a product.

Request:

curl -X DELETE 'https://api.4geeks.io/v1/products/{id}/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
    "code": 200,
    "title": "Product deleted",
    "content": "The product was successfully deleted.",
    "type": "success"
}

Error Handling¶

The API returns standard HTTP status codes to indicate the success or failure of a request. Below are some common errors:

Status Code	Error Message	Description
400	Bad Request	The request is malformed or missing required parameters.
401	Unauthorized	The request lacks valid authentication credentials.
404	Not Found	The requested resource (e.g., products ID) does not exist.
500	Internal Server Error	An unexpected error occurred on the server. Contact support for assistance.

Example error response:

{
    "error": "Unauthorized",
    "message": "Authentication credentials were not provided."
}