Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JuanSCaicedo/Api-Ecommerce/llms.txt

Use this file to discover all available pages before exploring further.

The cart is user-specific and requires a valid Bearer token on every request. All mutating operations (POST, PUT, DELETE) are throttled to 20 requests per minute per user; exceeding this limit returns a 429 Too Many Requests response. Each cart item is uniquely identified by a UUID generated at creation time.

​
GET /api/ecommerce/cart

Returns all cart items belonging to the authenticated user, ordered by creation time ascending. The carts value is wrapped in a data key by the CartEcommerceCollection resource. 
curl --request GET \
  --url https://your-domain.com/api/ecommerce/cart \
  --header "Authorization: Bearer <token>"

​
Response

{
  "carts": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": 12,
        "product_id": 42,
        "product": {
          "id": 42,
          "title": "Wireless Headphones Pro",
          "slug": "wireless-headphones-pro",
          "price_pen": 299900,
          "price_usd": 74.99,
          "imagen": "https://objectstorage.example.com/ecommerce/products/whp001.webp",
          "brand_id": 3,
          "brand": { "id": 3, "name": "Sony" }
        },
        "product_variation_id": 11,
        "product_variation": {
          "id": 11,
          "attribute_id": 2,
          "attribute": { "name": "Color", "type_attribute": "color" },
          "propertie_id": 7,
          "propertie": { "name": "Black", "code": "#000000" },
          "value_add": null,
          "variation_father": null
        },
        "quantity": 2,
        "price_unit": 299900,
        "subtotal": 299900,
        "total": 599800,
        "currency": "COP",
        "type_discount": null,
        "discount": null,
        "type_campaing": null,
        "code_cupon": null,
        "code_discount": null,
        "created_at": "2024-06-10 09:15 AM"
      }
    ]
  }
}
The carts field is an object with a data array (produced by CartEcommerceCollection), not a bare array. The embedded product summary uses price_pen and price_usd as the field names — unlike the full ProductEcommerceResource which uses price_cop.

​
POST /api/ecommerce/cart

Adds a new item to the authenticated user’s cart. The server validates stock availability and rejects duplicate product/variation combinations. Throttled to 20 requests per minute. 
curl --request POST \
  --url https://your-domain.com/api/ecommerce/cart \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": 42,
    "product_variation_id": 11,
    "quantity": 2,
    "price_unit": 299900,
    "subtotal": 299900,
    "total": 599800,
    "currency": "COP"
  }'

​
Body

​
product_id
integer
required
The ID of the product to add.
​
product_variation_id
integer
The ID of the specific product variation (e.g. a particular color/size combination). Omit or pass null for products without variations.
​
quantity
integer
required
Number of units to add. Must not exceed available stock (checked server-side against the variation stock if product_variation_id is provided, or the base product stock otherwise).
​
price_unit
number
required
Unit price at the time of adding to cart (in the selected currency). The client is responsible for passing the correct discounted price when a campaign is active.
​
subtotal
number
required
Price per unit after any applicable discount (used as the base for coupon application).
​
total
number
required
subtotal × quantity. Stored on the cart item for quick order total calculation.
​
currency
string
required
ISO 4217 currency code, e.g. "COP" or "USD".

​
Validation rules

  • If product_variation_id is provided: a cart item for the same (product_id, product_variation_id, user_id) combination must not already exist.
  • If product_variation_id is null: a cart item for the same (product_id, null, user_id) combination must not already exist.
  • quantity must not exceed the available stock of the variation (or base product).

​
Response — success

{
  "cart": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": 12,
    "product_id": 42,
    "...": "..."
  }
}

​
Response — duplicate item

{
  "message": 403,
  "message_text": "El producto y la variación ya se encuentra en el carrito, intente modificando la cantidad en el carrito."
}

​
Response — insufficient stock

{
  "message": 403,
  "message_text": "La cantidad solicitada supera el stock disponible."
}

​
PUT /api/ecommerce/cart/

Updates an existing cart item. The same duplicate and stock validations apply as for the POST endpoint, excluding the current item from the uniqueness check. Throttled to 20 requests per minute. 
curl --request PUT \
  --url https://your-domain.com/api/ecommerce/cart/550e8400-e29b-41d4-a716-446655440000 \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": 42,
    "product_variation_id": 11,
    "quantity": 3,
    "price_unit": 299900,
    "subtotal": 299900,
    "total": 899700,
    "currency": "COP"
  }'

​
Path parameters

ParameterTypeDescription
idstring (UUID)The cart item ID returned when the item was created.

​
Response

{
  "cart": { "...": "..." }
}

​
DELETE /api/ecommerce/cart/

Removes a single item from the cart by its UUID. Throttled to 20 requests per minute. 
curl --request DELETE \
  --url https://your-domain.com/api/ecommerce/cart/550e8400-e29b-41d4-a716-446655440000 \
  --header "Authorization: Bearer <token>"

​
Response

{
  "message": 200
}

​
DELETE /api/ecommerce/cart/delete_all

Removes all items from the authenticated user’s cart in a single operation.
This route is registered before the cart resource route in routes/api.php, so Laravel correctly matches delete_all as a named path rather than treating it as the {id} wildcard segment.
curl --request DELETE \
  --url https://your-domain.com/api/ecommerce/cart/delete_all \
  --header "Authorization: Bearer <token>"

​
Response

{
  "message": 200
}

​
POST /api/ecommerce/cart/apply_cupon

Applies a coupon code to all eligible cart items for the authenticated user. The server resolves which cart items qualify based on the coupon’s scope (product, category, or brand), recalculates subtotal and total for each matching item, and records the coupon code on those items. 
curl --request POST \
  --url https://your-domain.com/api/ecommerce/cart/apply_cupon \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "code_cupon": "SAVE10"
  }'

​
Body

​
code_cupon
string
required
The coupon code to apply, e.g. "SAVE10". Must match a coupon with state=1.

​
Coupon resolution logic

  1. The coupon is looked up by code with state=1. If not found → 403.
  2. If type_count=2 and num_use ≤ 0 (usage limit exhausted) → 403.
  3. If the coupon code is already applied to any item in the cart → 403.
  4. Each cart item is checked against the coupon’s scope:
    • type_cupone=1 — applies to specific products listed in cupon.products.
    • type_cupone=2 — applies to products belonging to any category listed in cupon.categories.
    • type_cupone=3 — applies to products from any brand listed in cupon.brands.
  5. For each matching item, the new subtotal is calculated:
    • type_discount=1 (percentage): subtotal = price_unit − price_unit × (discount / 100)
    • type_discount=2 (fixed amount): subtotal = price_unit − discount
    • total = subtotal × quantity
  6. The cart item is updated with type_discount, discount, code_cupon, subtotal, total. The type_campaing and code_discount fields are cleared to null.
  7. If type_count=2 and at least one item was discounted, cupon.num_use is decremented by 1.
  8. If no cart items matched the coupon’s scope → 403.

​
Response — success

{
  "message": 200,
  "message_text": "Se aplicó el cupón correctamente!"
}

​
Response — errors

{
  "message": 403,
  "message_text": "El cupón no es válido."
}

{
  "message": 403,
  "message_text": "El cupón ha alcanzado el límite de usos."
}

{
  "message": 403,
  "message_text": "El cupón ya fue aplicado."
}

{
  "message": 403,
  "message_text": "El cupón no aplica a ningún producto en el carrito."
}

​
Cart Item Response Fields

​
id
string (UUID)
Unique identifier for the cart item, generated as a UUID v4 at creation time.
​
user_id
integer
ID of the authenticated user who owns this cart item.
​
product_id
integer
ID of the product in this cart item.
​
product
object
Embedded product summary containing: id, title, slug, price_pen, price_usd, imagen, brand_id, brand.
​
product_variation_id
integer | null
ID of the selected variation, or null for base products.
​
product_variation
object | null
Embedded variation detail including attribute, propertie, value_add, and variation_father (the parent variation when this is a sub-variation / anidado). null when no variation is selected.
​
quantity
integer
Number of units in the cart.
​
price_unit
number
Original unit price at the time the item was added.
​
subtotal
number
Unit price after coupon/discount application. Equals price_unit when no discount is applied.
​
total
number
subtotal × quantity. The line-item total.
​
currency
string
ISO 4217 currency code, e.g. "COP" or "USD".
​
code_cupon
string | null
Coupon code applied to this item. null if no coupon has been applied.
​
discount
number | null
The discount value applied (either a percentage or a fixed amount). null if no discount is active.
​
type_discount
integer | null
Discount type: 1 = percentage, 2 = fixed amount. null if no discount is active.
​
type_campaing
integer | null
Campaign type of any applied campaign discount. Cleared to null when a coupon is applied.
​
code_discount
string | null
Campaign discount code. Cleared to null when a coupon is applied.
​
created_at
string
Creation timestamp formatted as "YYYY-MM-DD hh:mm AM/PM".

Build docs developers (and LLMs) love

Get started for freeTalk to us