Remove stock from a SKU

POST/v2/experiences/{experienceId}/retail-skus/{skuId}/remove-stock

Requires your API key in the X-API-Key header.

Takes quantity units off the SKU's on-hand stock (breakage, write-offs), records a MANUAL_REMOVAL entry in its stock ledger, and returns the entry and the new count. Organizer only (403 otherwise). Stock can't go below zero (400, RETAIL_STOCK_REMOVAL_EXCEEDS_ON_HAND), and the SKU must count stock (400, RETAIL_STOCK_NOT_TRACKED).

Requestbash
curl -X POST "https://api.turneo.co/v2/experiences/8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f/retail-skus/8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d/remove-stock" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 2,
    "note": "Damaged in storage"
  }'

Path parameters

  • experienceIdstring (uuid)required

    UUID of the retail product.

    Example:
    8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f
  • skuIdstring (uuid)required

    UUID of the SKU.

    Example:
    8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d

Request bodyapplication/json, required

  • quantityintegerrequired

    Number of units. Always positive; the endpoint sets the direction.

    Limits:
    minimum 1
    Example:
    20
  • notestringnullable

    Optional note stored on the ledger entry.

    Limits:
    up to 255 characters
    Example:
    Delivery from supplier
Example: writeOff
writeOffjson
{
  "quantity": 2,
  "note": "Damaged in storage"
}

Responses

200object

The recorded ledger entry and the SKU's new on-hand count.

  • movementobject

    One entry in a SKU's stock ledger.

    Child fields
    • idstring (uuid)

      Entry UUID.

      Example:
      5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a
    • deltainteger

      Change to the on-hand count; positive for a restock or return, negative for a sale or removal.

      Example:
      -1
    • reasonstring

      Why the stock moved.

      Allowed values:
      RESTOCKMANUAL_REMOVALSALEREFUND_RETURNCORRECTION
      Example:
      SALE
    • actorNamestringnullable

      Account that made a manual movement. Null for sales and returns.

      Example:
      Hotel Example Shop
    • retailItemIdstring (uuid)nullable

      The retail item a SALE or REFUND_RETURN entry came from.

      Example:
      7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a
    • notestringnullable

      Note recorded with a manual movement.

      Example:
      Delivery from supplier
    • createdAtstring (date-time)

      When the movement was recorded.

      Example:
      2026-07-15T09:12:00Z
  • stockQuantityinteger

    Units on hand after the movement.

    Example:
    32
Response 200json
{
  "movement": {
    "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
    "delta": -1,
    "reason": "SALE",
    "actorName": "Hotel Example Shop",
    "retailItemId": "7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a",
    "note": "Delivery from supplier",
    "createdAt": "2026-07-15T09:12:00Z"
  },
  "stockQuantity": 32
}

Errors

400

Validation failed. Inspect errors[].field and errors[].code.

401

Missing or invalid X-API-Key header.

403

The API key is valid but not allowed to perform this action on this resource.

404

The resource does not exist or belongs to another partner (existence is not leaked across partners).

Error body
  • typestring

    Error class.

    Allowed values:
    validation_errorclient_errorserver_error
    Example:
    validation_error
  • errorsobject[]
    Child fields
    • codestring

      Machine-readable error code.

      Example:
      required
    • fieldstringnullable

      Offending field, or null/'general' for non-field errors.

      Example:
      startTime
    • messagestring

      Human-readable message.

      Example:
      This field is required.
Response 400json
{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "field": "startTime",
      "message": "This field is required."
    }
  ]
}