Skip to main content
PUT
/
receipts
/
{id}
Update receipt (comprehensive) or close receipt
curl --request PUT \
  --url https://integrations.clopos.com/open-api/receipts/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-brand: <api-key>' \
  --header 'x-token: <api-key>' \
  --header 'x-venue: <api-key>' \
  --data '
{
  "id": 123,
  "cid": "<string>",
  "payment_methods": [
    {
      "id": 123,
      "name": "<string>",
      "amount": 123
    }
  ],
  "closed_at": "<string>"
}
'
{
  "success": true,
  "data": {
    "id": 123,
    "venue_id": 123,
    "cash_shift_cid": "<string>",
    "cid": "<string>",
    "user_id": 123,
    "open_by_user_id": 123,
    "close_by_user_id": 123,
    "courier_id": 123,
    "seller_id": 123,
    "terminal_id": 123,
    "source": "<string>",
    "closed_terminal_id": 123,
    "service_notification_id": 123,
    "table_id": 123,
    "hall_id": 123,
    "customer_id": 123,
    "sale_type_id": 123,
    "is_returns": true,
    "guests": 123,
    "status": 123,
    "lock": true,
    "inventory_status": 123,
    "report_status": 123,
    "meta": {
      "preprint_count": 123,
      "sale_type": {
        "name": "<string>"
      },
      "user": {
        "name": "<string>"
      },
      "terminal_updated_at": 123,
      "availiableDeposit": 123,
      "check_close_event": {
        "checked": true,
        "operated_at": "<string>",
        "fails": [
          "<unknown>"
        ]
      }
    },
    "suspicion": 123,
    "printed": true,
    "total": 123,
    "subtotal": 123,
    "original_subtotal": 123,
    "gift_total": 123,
    "totalCost": 123,
    "payment_methods": [
      {
        "id": 123,
        "name": "<string>",
        "amount": 123
      }
    ],
    "fiscal_id": "<string>",
    "by_cash": 123,
    "by_card": 123,
    "remaining": 123,
    "discount_type": 123,
    "discount_value": 123,
    "discount_rate": 123,
    "rps_discount": 123,
    "service_charge": 123,
    "service_charge_value": 123,
    "i_tax": 123,
    "delivery_fee": 123,
    "e_tax": 123,
    "total_tax": 123,
    "description": "<string>",
    "address": "<string>",
    "terminal_version": "<string>",
    "loyalty_type": "<string>",
    "loyalty_value": 123,
    "order_status": "<string>",
    "order_number": "<string>",
    "created_at": "<string>",
    "updated_at": "<string>",
    "terminal_updated_at": "<string>",
    "closed_at": "<string>",
    "shift_date": "<string>",
    "deleted_at": "<string>",
    "gift_count": 123,
    "total_discount": 123,
    "properties": {
      "daily_id": 123,
      "monthly_id": 123
    },
    "receipt_products": [
      {
        "id": 123,
        "cid": "<string>",
        "product_id": 123,
        "receipt_id": 123,
        "product_hash": "<string>",
        "meta": {},
        "count": 123,
        "portion_size": 123,
        "total": 123,
        "price": 123,
        "cost": 123,
        "is_gift": true,
        "preprint_count": 123,
        "station_printed_count": 123,
        "station_aborted_count": 123,
        "seller_id": 123,
        "loyalty_type": "<string>",
        "loyalty_value": 123,
        "discount_rate": 123,
        "discount_value": 123,
        "discount_type": 123,
        "total_discount": 123,
        "subtotal": 123,
        "receipt_discount": 123,
        "created_at": "<string>",
        "updated_at": "<string>",
        "terminal_updated_at": "<string>",
        "deleted_at": "<string>",
        "receipt_product_modificators": [
          "<unknown>"
        ],
        "taxes": [
          "<unknown>"
        ]
      }
    ],
    "stock_operations": [
      "<unknown>"
    ],
    "customer": {}
  },
  "time": 123,
  "timestamp": "<string>",
  "unix": 123,
  "message": "<string>"
}

​
Purpose

Comprehensively update a receipt using the PUT method. This method allows you to update multiple fields at once and can also be used to close receipts. Critical Requirements:
  • The cid and id fields must not change. If different values are sent, the system will treat it as a new receipt and return an error.
  • All fields in the request body must be provided (full receipt object update).
Key Differences from PATCH:
  • PATCH: Updates only limited fields (order_status, order_number, fiscal_id, lock) and can update receipts after they are closed.
  • PUT: Allows comprehensive updates of multiple fields including delivery_fee, description, guests, discount_type, discount_value, discount_rate, customer_id, and can also close receipts.

​
HTTP Request

PUT https://integrations.clopos.com/open-api/receipts/{id}

​
Path Parameters

ParameterTypeDescription
idnumberUnique identifier of the receipt to update.

​
Request Body Schema

The request body must include the complete receipt object. The following fields can be updated:
FieldTypeRequiredDescription
cidstring (UUID)YesClient identifier. Must match the existing receipt’s CID - cannot be changed.
idnumberYesReceipt ID. Must match the path parameter - cannot be changed.
delivery_feeintegerNoDelivery fee amount.
descriptionstringNoReceipt description. Maximum 500 characters.
order_numberstringNoOrder number identifier (e.g., "002").
order_statusstring (enum)NoOrder status. Valid values: "NEW", "SCHEDULED", "IN_PROGRESS", "READY", "PICKED_UP", "COMPLETED", "CANCELLED".
guestsnumberNoNumber of guests.
discount_rateintegerNoDiscount rate.
discount_typeinteger (enum)NoDiscount type. Valid values: 1 (percent), 2 (amount).
discount_valuenumberNoDiscount value. Required when discount_type is 2 (amount).
customer_idintegerNoCustomer identifier. When adding or changing a customer, you must also provide the meta.customer data structure.
closed_atstringNoTimestamp when the receipt was closed. Can be set to close the receipt. Format: "YYYY-MM-DD HH:MM:SS" or empty string "" to keep open.
meta.customerobjectNoCustomer metadata object. Required when customer_id is provided. See Customer Meta Data structure below.

​
Customer Meta Data

When adding or changing a customer to a receipt, you must provide the meta.customer data structure in your request. This data is not automatically fetched - you need to include it manually. The customer data can be obtained from the Customers API. The meta.customer structure should follow this format: 
{
  "name": "Rahid Akhundzada",
  "bonus": 0,
  "cashback": 54.69,
  "balance": -108,
  "desc": null,
  "code": null,
  "phone": "+994 70 540 10 40",
  "group_name": "My Customers",
  "group_id": 1
}

​
Request Example

curl --location --request PUT 'https://integrations.clopos.com/open-api/receipts/1' \
  --header 'Content-Type: application/json' \
  --header 'x-token: oauth_example_token' \
  --header 'x-brand: openapitest' \
  --header 'x-venue: 1' \
  --data '{
    "id": 1,
    "cid": "a7890398-d8ae-41cb-b95f-4d21458d72cf",
    "delivery_fee": 5,
    "description": "Updated receipt description",
    "order_number": "002",
    "order_status": "IN_PROGRESS",
    "guests": 2,
    "discount_rate": 10,
    "discount_type": 1,
    "discount_value": 0,
    "customer_id": 123,
    "closed_at": "",
    "meta": {
      "customer": {
        "name": "Rahid Akhundzada",
        "bonus": 0,
        "cashback": 54.69,
        "balance": -108,
        "desc": null,
        "code": null,
        "phone": "+994 70 540 10 40",
        "group_name": "My Customers",
        "group_id": 1
      }
    }
  }'

​
Complete Receipt Update Schema

For a full receipt update, you can include the complete receipt object structure. Below is the comprehensive schema: 
{
  "cid": "a7890398-d8ae-41cb-b95f-4d21458d72cf",
  "id": 1,
  "user_id": 1,
  "table_id": 29,
  "hall_id": 1,
  "guests": 1,
  "total": 9.27,
  "subtotal": 9,
  "original_subtotal": 9,
  "printed": false,
  "description": "",
  "closed_at": "",
  "service_charge": 3,
  "service_charge_value": 0.27,
  "discount_type": 0,
  "created_at": "2025-11-20 11:13:03",
  "discount_value": 0,
  "discount_rate": 0,
  "customer_discount_type": 0,
  "address": "",
  "payment_methods": [],
  "sale_type_id": 1,
  "gift_total": 0,
  "delivery_fee": 0,
  "order_status": "IN_PROGRESS",
  "order_number": "002",
  "customer_id": 123,
  "meta": {
    "user": {
      "name": "Clopos Test",
      "role": "owner"
    },
    "sale_type": {
      "name": "In-store",
      "channel": "IN"
    },
    "customer": {
      "name": "Rahid Akhundzada",
      "bonus": 0,
      "cashback": 54.69,
      "balance": -108,
      "desc": null,
      "code": null,
      "phone": "+994 70 540 10 40",
      "group_name": "My Customers",
      "group_id": 1
    },
    "preprint_count": 0,
    "terminal_updated_at": 1763622813078,
    "service_charge_calc_type": 0,
    "lastAddedProductTime": "2025-11-20T07:13:33.394Z",
    "multi_price": {
      "price_list_id": 80
    },
    "table": {
      "name": "Extra 27",
      "full_name": "Hall / Extra 27"
    },
    "hall": {
      "name": "Hall"
    },
    "availiableDeposit": 9,
    "hash": "e2f707ef66af00bc8e32b02080053321"
  },
  "terminal_id": 3,
  "service_notification_id": null,
  "rps_discount": 0,
  "total_tax": 0,
  "i_tax": 0,
  "e_tax": 0,
  "terminal_version": 3253,
  "open_by_user_id": 1,
  "properties": {
    "changes": {
      "service_charge_value": {
        "timestamp": 1763622813078,
        "oldValue": 0.12,
        "newValue": 0.27
      }
    }
  },
  "receipt_products": [
    {
      "id": 38514,
      "cid": "1abdefd3-b21c-4766-85ee-b7f34b4ad3da",
      "product_id": 333,
      "product_hash": "333",
      "created_at": "1763622801594",
      "updated_at": "1763622801595",
      "count": 1,
      "price": 4,
      "total": 4,
      "receipt_product_modificators": [],
      "station_printed_count": 0,
      "station_aborted_count": 0,
      "preprint_count": 0,
      "is_gift": 0,
      "meta": {
        "product": {
          "name": "Double Espresso",
          "price": 4,
          "modifier_name": "",
          "discountable": true,
          "sold_by_weight": false,
          "priceWithoutTaxes": 4,
          "ignore_service_charge": false,
          "barcode": "",
          "category": {
            "id": 30,
            "name": "QƏHVƏ"
          },
          "type": "DISH",
          "has_portion": false,
          "has_excise": false
        },
        "product_price": {},
        "originalPrice": 4,
        "total_gift": 0,
        "subtotalWithTax": 0,
        "discountedPrice": 0,
        "terminal_updated_at": 1763622801357,
        "created_terminal": 3,
        "excise": "",
        "excise_short": "",
        "original_subtotal": 4
      },
      "discount_rate": 0,
      "discount_value": 0,
      "discount_type": 0,
      "total_discount": 0,
      "subtotal": 4,
      "receipt_discount": 0,
      "portion_size": 1,
      "taxes": []
    }
  ]
}

​
Response

​
200 OK — Receipt Updated

The response returns the full receipt data with all fields updated: 
{
  "success": true,
  "data": {
    "id": 1,
    "cid": "a7890398-d8ae-41cb-b95f-4d21458d72cf",
    "delivery_fee": 5,
    "description": "Updated receipt description",
    "order_number": "002",
    "order_status": "IN_PROGRESS",
    "guests": 2,
    "discount_rate": 10,
    "discount_type": 1,
    "discount_value": 0,
    "customer_id": 123,
    "meta": {
      "customer": {
        "name": "Rahid Akhundzada",
        "bonus": 0,
        "cashback": 54.69,
        "balance": -108,
        "desc": null,
        "code": null,
        "phone": "+994 70 540 10 40",
        "group_name": "My Customers",
        "group_id": 1
      }
    }
  }
}

​
400 Bad Request — Validation Error

​
CID or ID Mismatch

If the cid or id in the request body does not match the existing receipt, an error will be returned: 
{
  "success": false,
  "error": "validation_failed",
  "message": "CID and ID cannot be changed. Different values will be treated as a new receipt."
}

​
Invalid Field Values

{
  "success": false,
  "error": "validation_failed",
  "message": "Invalid field values provided"
}

​
404 Not Found — Receipt Not Found

{
  "success": false,
  "error": "not_found",
  "message": "Receipt not found"
}

​
Field Reference

FieldTypeDescriptionConstraints
cidstring (UUID)Client identifierRequired. Must match existing receipt CID - cannot be changed.
idnumberReceipt IDRequired. Must match path parameter - cannot be changed.
delivery_feeintegerDelivery fee amountOptional
descriptionstringReceipt descriptionOptional. Maximum 500 characters.
order_numberstringOrder number identifierOptional
order_statusstring (enum)Order statusOptional. Valid values: "NEW", "SCHEDULED", "IN_PROGRESS", "READY", "PICKED_UP", "COMPLETED", "CANCELLED".
guestsnumberNumber of guestsOptional
discount_rateintegerDiscount rateOptional
discount_typeinteger (enum)Discount typeOptional. 1 = percent, 2 = amount
discount_valuenumberDiscount valueOptional. Required when discount_type is 2 (amount).
customer_idintegerCustomer identifierOptional. When provided, you must also include meta.customer data structure.
meta.customerobjectCustomer metadataOptional. Required when customer_id is provided. Must be manually included in the request.
closed_atstringTimestamp when receipt was closedOptional. Can be set to close the receipt. Format: "YYYY-MM-DD HH:MM:SS" or "" to keep open.

​
Notes

  • The cid and id fields must not change. If different values are sent, the system will treat it as a new receipt and return an error.
  • This method can be used to close receipts by setting the closed_at field.
  • When customer_id is provided, you must also include the meta.customer data structure in your request. This data is not automatically fetched - you need to provide it manually. You can obtain customer data from the Customers API.
  • The PUT method allows comprehensive updates of multiple fields at once, unlike PATCH which only updates limited fields.
  • All fields in the request body should be provided for a complete update, though only the updatable fields listed above will be processed.

Authorizations

​
x-token
string
header
required

Access token obtained from /auth endpoint

​
x-brand
string
header
required

Brand identifier

​
x-venue
string
header
required

Venue identifier

Path Parameters

​
id
integer
required

Receipt ID

Body

application/json
​
id
integer
required

Receipt identifier (must match path parameter)

​
cid
string
required

Transaction UUID

​
payment_methods
object[]
required

List of payment methods with amounts

Minimum array length: 1
​
closed_at
string
required

Closing timestamp in format 'YYYY-MM-DD HH:mm:ss'. Must be greater than created_at.

Response

Receipt closed successfully

​
success
boolean
​
data
object
​
time
integer
​
timestamp
string
​
unix
integer
​
message
string