Inventory - Curosa

Overview

The Inventory endpoint allows you to retrieve factory stock information for your products. Factory stock represents inventory that is available at your manufacturing facility or warehouse before it has been allocated to specific distribution centres or orders. This endpoint provides visibility into your total stock quantities, allocated quantities, and free (available) quantities.

Understanding Stock Quantities

Stock Quantity: Total inventory available at your factory/warehouse
Allocated Quantity: Stock that has been reserved or allocated for specific orders
Free Quantity: Available stock that can be allocated (stock_quantity - stock_quantity_allocated)

Use this endpoint to monitor your factory stock levels and identify products that may need restocking or have excess inventory available for allocation.

Authentication

This endpoint requires authentication. Include your API key in the Authorization header. For more information on obtaining an API key, see the Authentication guide.

List Factory Stock

Retrieve a list of all factory stock levels for your products.

Request

curl -X GET "https://api.curosa.com/v1/factory-stocks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Optional Query Parameters

You can filter factory stock by quantity ranges using the following query parameters:

stock_quantity_gte (integer, optional): Filter for products with stock quantity greater than or equal to this value
stock_quantity_lte (integer, optional): Filter for products with stock quantity less than or equal to this value
stock_quantity_allocated_gte (integer, optional): Filter for products with allocated stock quantity greater than or equal to this value
stock_quantity_allocated_lte (integer, optional): Filter for products with allocated stock quantity less than or equal to this value

Example with filters:

curl -X GET "https://api.curosa.com/v1/factory-stocks?stock_quantity_gte=10&stock_quantity_lte=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

All responses are returned in JSON format:

{
    "data": [
        {
            "sku": "T3272P287613",
            "platform_sku": "367.983.903",
            "stock_quantity": 150,
            "stock_quantity_allocated": 0,
            "stock_quantity_free": 150
        },
        {
            "sku": "T3272P355456",
            "platform_sku": "107.871.472",
            "stock_quantity": 0,
            "stock_quantity_allocated": 0,
            "stock_quantity_free": 0
        }
    ],
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": "https://curosa.com/api/v1/factory-stocks?cursor=eyJmYWN0b3J5X3N0b2Nrcy5pZCI6MiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"
    },
    "meta": {
        "path": "https://curosa.com/api/v1/factory-stocks",
        "per_page": 2500,
        "next_cursor": "eyJmYWN0b3J5X3N0b2Nrcy5pZCI6MiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
        "prev_cursor": null
    }
}

Response Fields:

sku (string): Your internal SKU identifier for the product
platform_sku (string): The Curosa platform SKU identifier for the product
stock_quantity (integer): The total stock quantity available at the factory
stock_quantity_allocated (integer): The quantity that has been allocated to orders or distribution centres
stock_quantity_free (integer): The quantity that is free and available for allocation (calculated as stock_quantity - stock_quantity_allocated)

Pagination:

This endpoint uses cursor-based pagination. The response includes:

links: Navigation links for pagination (first, last, prev, next)
meta: Pagination metadata
- path: The base path for this endpoint
- per_page: Number of items per page (default is 2500)
- next_cursor: Cursor token for the next page (use in cursor query parameter)
- prev_cursor: Cursor token for the previous page (use in cursor query parameter)

To fetch the next page, include the cursor query parameter with the value from meta.next_cursor:

curl -X GET "https://api.curosa.com/v1/factory-stocks?cursor=eyJmYWN0b3J5X3N0b2Nrcy5pZCI6MiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Factory Stock Level

Update the factory stock quantity for a single product by providing the SKU and new stock quantity.

Request

curl -X POST "https://api.curosa.com/v1/factory-stocks/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "ABC123",
    "stock_quantity": 10
  }'

Request Body Fields:

sku (string, required): Your internal SKU identifier for the product
stock_quantity (integer, required): The new total stock quantity to set for this product

Response

The response includes both successfully updated items and any errors encountered:

{
    "updated": [
        {
            "platform_sku": "880.033.390",
            "sku": "ABC123",
            "stock_quantity": 10
        }
    ],
    "errors": []
}

Response Fields:

updated (array): Array of successfully updated stock items
- platform_sku (string): The Curosa platform SKU identifier
- sku (string): Your internal SKU identifier
- stock_quantity (integer): The updated stock quantity
errors (array): Array of items that failed to update, if any
- platform_sku (string|null): The platform SKU if found, otherwise null
- sku (string): Your internal SKU identifier that failed
- stock_quantity (integer|null): The requested stock quantity, or null if the product wasn't found
- error (string): Error message describing why the update failed (e.g., "Product not found")

Example with error:

{
    "updated": [],
    "errors": [
        {
            "platform_sku": null,
            "sku": "ABC1234",
            "stock_quantity": null,
            "error": "Product not found"
        }
    ]
}

Bulk Update Factory Stock Levels

Update factory stock quantities for multiple products in a single request. This is more efficient than making individual update requests for each product.

Request

curl -X POST "https://api.curosa.com/v1/factory-stocks/bulk-update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
        "sku": "ABC123",
        "stock_quantity": 10
    },
    {
        "sku": "DEF456",
        "stock_quantity": 25
    },
    {
        "sku": "GHI789",
        "stock_quantity": 5
    }
  ]'

Request Body:

The request body is an array of objects, each containing:

sku (string, required): Your internal SKU identifier for the product
stock_quantity (integer, required): The new total stock quantity to set for this product

Response

The response includes both successfully updated items and any errors encountered. Items are processed independently, so some may succeed while others fail:

{
    "updated": [
        {
            "platform_sku": "880.033.390",
            "sku": "ABC123",
            "stock_quantity": 10
        },
        {
            "platform_sku": "574.478.508",
            "sku": "DEF456",
            "stock_quantity": 25
        }
    ],
    "errors": [
        {
            "platform_sku": null,
            "sku": "GHI789",
            "stock_quantity": null,
            "error": "Product not found"
        }
    ]
}

Response Fields:

updated (array): Array of successfully updated stock items
- platform_sku (string): The Curosa platform SKU identifier
- sku (string): Your internal SKU identifier
- stock_quantity (integer): The updated stock quantity
errors (array): Array of items that failed to update
- platform_sku (string|null): The platform SKU if found, otherwise null
- sku (string): Your internal SKU identifier that failed
- stock_quantity (integer|null): The requested stock quantity, or null if the product wasn't found
- error (string): Error message describing why the update failed

Important Notes:

Each item in the bulk update is processed independently. If one item fails, others can still succeed.
The updated and errors arrays will contain results for all items in your request.
Always check the errors array to identify any products that couldn't be updated.
Use bulk updates when updating multiple products to reduce the number of API calls and improve performance.