Skip to main content

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​

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.