> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.kreezalid.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Apply a custom unit price to an item when added to cart

## Overview

Developers working on storefronts or client interfaces for marketplace platforms can leverage this feature to impose a custom unit price for items as they are added to a cart, bypassing the default pricing stored in the database. This feature might be especially pertinent for implementing promotional offers, applying unique pricing models, or accommodating other specialized e-commerce use cases.

## API Endpoint Details

-   **HTTP Method:** POST
-   **Endpoint:** `/front_api/v1/carts/{cart_url_key}`
-   **Documentation:** [Add a listing to cart](https://kreezalid.stoplight.io/docs/front-api/953c6060bf8b1-add-a-listing-to-cart)

## Request Payload Parameters

-   `listing_id`: (integer, required) - ID of the listing/item.
-   `quantity`: (integer, required) - Number of units to add to the cart.
-   `custom_unit_price`: (number, optional) - Custom price per unit. If not provided, the default price will be applied.
-   `options`: (object, optional) - Additional attributes related to the item.
    -   `attribute1`: (integer, optional) - Attribute ID.
    -   `attribute2`: (integer, optional) - Attribute ID.
-   `addons`: (array of integers, optional) - Array of addon IDs.

## Example Request

```
{
	"listing_id": 221329,
	"quantity": 1,
	"custom_unit_price": 1025,
	"options": {
		"attribute1": 14521,
		"attribute2": 15421
	},
	"addons": [25729, 25731]
}
```

## Parameter Details

### `custom_unit_price`

-   **Type**: Number
-   **Description**: When provided, it applies a custom unit price for the item, overriding the default price from the database.

## Usage Scenarios

### Implementing Promotions or Discounts

Developers can utilize the `custom_unit_price` parameter to programmatically apply discounts or special pricing at runtime based on specific conditions or promotional logic.

### Tailoring User-Specific Prices

In cases where individual pricing is applicable (e.g., tiered pricing, user-specific discounts, etc.), developers can apply the pricing logic in the storefront/client app and pass the tailored price via the `custom_unit_price` parameter.

## Considerations

### Data Validation

Ensure `custom_unit_price` is validated for being a positive integer or zero before being sent in the API request to avoid potential errors or mispricing.

### Security and Authorization

Validate and ensure that the usage of `custom_unit_price` complies with applicable regulations and platform policies. Be mindful to safeguard against pricing manipulation or exploitation from client-side implementations.

## Error Handling

Be prepared to handle errors gracefully, ensuring that in the case where the API request fails or returns an error (e.g., due to invalid `custom_unit_price` values), the user experience remains uninterruptive and informative error messages are provided.

## Monitoring and Auditing

Monitor the usage of the `custom_unit_price` functionality to observe any anomalies, misuse, or patterns that might suggest improvements or refinements to the feature. Implement adequate logging to ensure that custom pricing applications are auditable and traceable for future reference or debugging.

## Conclusion

By integrating the `custom_unit_price` feature into client storefronts or interfaces, developers can harness the flexibility of imposing prices that adhere to dynamic, promotional, or user-specific pricing logics, thereby enhancing the platform's pricing model's versatility and capability. Ensure rigorous testing and validation to uphold pricing integrity and accuracy across the platform’s marketplace.