External API Action Scenarios

Example scenarios and flows that can be implemented via the External API Action plugin are listed below.

Payment Flow

Note: Even if the Public API supports the payment-sending flow, since no fiscal receipt is printed on the Simpra Terminal, payments received should only be relayed to the cashier as a message and must not be sent as a payment.

The check is sent to the 3rd party application

Header:

The simpra-action-token parameter is sent in the header; you can check it from the External API Action plugin.

simpra-action-token: b5a573f1aa50f6dcdd556565f3fbe6e9

Body:

The request body contains the check_id, property_id, and option parameters:

check_id: the unique id of the check being processed; it will be used for operations performed on the check

property_id: the unique id of the property the operation was performed on; used to determine which branch the request was sent from

option: information specific to the operation, generally used to identify the guest; information such as a QR code generated from the mobile app, phone number, or membership number is used

{
  "check_id": "a27ee804-c9f3-4bc1-9faf-aaaccb742d57",
  "property_id": "131270e1-6d14-4977-950d-048985f3296d",
  "option": "QR Kod testi 111111"
}

Note: A service can also be triggered from Simpra POS without the cashier pressing any button. As a result, the option line will not be present in the request sent.

{
  "check_id": "a27ee804-c9f3-4bc1-9faf-aaaccb742d57",
  "property_id": "131270e1-6d14-4977-950d-048985f3296d"
}

The 3rd party application adds a payment to the check and unlocks it

For payment, a request is sent to the following endpoint using the Simpra Connect token:

/apps/api/v1/checks/{check_id}/check_payments

📄 Reference: Add Payment to Check

Expected body example for the request:

{
  "payments": [
    {
      "amount": 50,
      "payment_id": "eb9dacd9-40cd-4dcc-8da2-8610eb554a17"
    }
  ]
}

After the payment request succeeds, the check must be unlocked; for this, a request is sent to the following URL using the External API Action token:

/apps/api/v1/checks/{check_id}/unlock

📄 Reference: Unlock Check

Expected body example for the request:

{
  "Message": "100 TL payment added"
}

Example flow video: https://drive.google.com/file/d/1f_wmKccpBLEnrn1MNPtPdkuiv2gsIp6S/view?usp=drive_link

Discount Flow

The check is sent to the 3rd party application

Header:

The simpra-action-token parameter is sent in the header; you can check it from the External API Action plugin.

simpra-action-token: b5a573f1aa50f6dcdd556565f3fbe6e9

Body:

The request body contains the check_id, property_id, and option parameters (same as the Payment Flow above).

{
  "check_id": "a27ee804-c9f3-4bc1-9faf-aaaccb742d57",
  "property_id": "131270e1-6d14-4977-950d-048985f3296d",
  "option": "QR Kod testi 111111"
}

The 3rd party application adds a discount to the check and unlocks it

For the discount, a request is sent to the following endpoint using the Simpra Connect token:

/apps/api/v1/checks/{check_id}/check_discounts

📄 Reference: Add Discount to Check

Expected body example for the request below; here the amount value must be determined based on the discount type:

If "type": "percentage", the amount value is calculated as a percentage and applied as a percentage of the amount due

If "type": "amount", the amount value sent in the body will be evaluated as a fixed amount

{
  "discount_id": "024d95cc-4638-4fb1-bede-0ef15c0cd046",
  "amount": 10
}

When a discount needs to be sent for a specific item within the check, a request is first sent to the check with check_id and the check_items within the check are found. Then, to apply a discount to a specific item, a request is sent as follows:

{
  "discounts": [
    {
      "discount_id": "550e8400-e29b-41d4-a716-446655440000",
      "value": 10.0,
      "check_item_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
    },
    {
      "discount_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "value": 5.0
    }
  ]
}

After the discount request succeeds, the check must be unlocked; for this, a request is sent to the following URL using the External API Action token:

/apps/api/v1/checks/{check_id}/unlock

📄 Reference: Unlock Check

Expected body example for the request:

{
  "Message": "Discount added"
}

Example flow video: https://drive.google.com/file/d/1ZAVFf9qf0bt08SNVw7wuGJ10GJboX2Ko/view?usp=drive_link

Add Item Flow

To add an item to an existing check, while the check is with the service, a request is sent to the following endpoint:

/apps/api/v1/checks/{check_id}/check_items

📄 Reference: Create Check Item

Example body for the request below. menu_items[].id is a required field for the request.

{
  "menu_items": [
    {
      "id": "090de589-398d-4446-b853-ba1ad989dae2",
      "quantity": 2,
      "notes": ["hot"]
    }
  ]
}

Example request for a condiment or combo item is below; for an item with condiments, menu_items[].condiments[].id is a required field.

Item with condiments:

{
  "menu_items": [
    {
      "id": "090de589-398d-4446-b853-ba1ad989dae2",
      "quantity": 2,
      "condiments": [
        {
          "id": "19f7b0f5-fa49-4918-98c4-142ad2a14730"
        }
      ],
      "notes": ["hot"]
    }
  ]
}

Example request for a combo item:

{
  "menu_items": [
    {
      "id": "090de589-398d-4446-b853-ba1ad989dae2",
      "quantity": 2,
      "combo_items": [
        {
          "id": "3213d733-5311-440b-ad41-92640a7250ff",
          "combo_group_item_id": "4d0a869e-7bee-4c58-ae25-6d3bf20622f8"
        }
      ],
      "notes": ["hot"]
    }
  ]
}

After the add-item request succeeds, the check must be unlocked; for this, a request is sent to the following URL using the External API Action token:

/apps/api/v1/checks/{check_id}/unlock

📄 Reference: Unlock Check

Expected body example for the request:

{
  "Message": "Item added"
}

Example flow video: https://drive.google.com/file/d/1nHu54Tl0KKKBHXgs3qAz1QNDZaPFKuBU/view?usp=drive_link

Cancel Item Flow

To cancel an item from an existing check, while the check is with the service, a request is sent to the following endpoint:

/apps/api/v1/checks/{check_id}/check_items/{check_item_id}/cancel

📄 Reference: Cancel Check Item

A reason_id can be sent in the body of the request. If it is not sent, the reason defined in the system is used.

After the cancel-item request succeeds, the check must be unlocked; for this, a request is sent to the following URL using the External API Action token:

/apps/api/v1/checks/{check_id}/unlock

📄 Reference: Unlock Check

Expected body example for the request:

{
  "Message": "Item cancelled"
}

Example flow video: https://drive.google.com/file/d/17SkTvtzMQ_eYbPJ3auPde3wodG8Duj43/view?usp=drive_link

Add / Remove Service Charge on Check Flow

Add

To add a service charge to an existing check, the following endpoint is used. service_charge_id is a required field.

/apps/api/v1/checks/{check_id}/check_service_charges

📄 Reference: Add Service Charge to Check

Example request below. If the service charge is user-defined, amount is sent; if it is a fixed value, sending amount is not necessary. For a service charge configured as %, amount will be applied as a percentage; for one configured as TL, amount will be added as TL.

{
  "service_charge_id": "eb9dacd9-40cd-4dcc-8da2-8610eb554a17",
  "amount": 50
}

After the service charge request succeeds, the check must be unlocked; for this, a request is sent to the following URL using the External API Action token:

/apps/api/v1/checks/{check_id}/unlock

📄 Reference: Unlock Check

Expected body example for the request:

{
  "Message": "Service charge added"
}

Example flow video: https://drive.google.com/file/d/1uCpmIBVL_JUR0Z2y1W6MYk9nfXNlAPNx/view?usp=drive_link

Remove

The endpoint to call and the example request for removing a service charge are below. The request must be sent as DELETE:

/apps/api/v1/checks/{check_id}/check_service_charges/{check_service_charge_id}

📄 Reference: Remove Check Service Charge

After the service charge removal request succeeds, the check must be unlocked; for this, a request is sent to the following URL using the External API Action token:

/apps/api/v1/checks/{check_id}/unlock

📄 Reference: Unlock Check

Expected body example for the request:

{
  "Message": "Service charge removed"
}

Example flow video: https://drive.google.com/file/d/1OTXG7OEflh1Sh_efDskCxuh7KvWA-i_b/view?usp=drive_link

Add Note to Check Flow

To add a note to an existing check, the following endpoint is used:

/apps/api/v1/checks/{check_id}/add_note

📄 Reference: Add Note to Check

Example body for the request:

{
  "note": "Payment was made online!"
}

Example flow video: https://drive.google.com/file/d/13KCLnHhRJCKPoiLRKdjxVj2jbixfFZVs/view?usp=drive_link

Restricting Actions via the Unlock Parameter Flow

For a flow that, when the check sent to the service is unlocked with an extra parameter, restricts the operations the cashier can perform once the check is opened, a request should be sent as follows:

/apps/api/v1/checks/{check_id}/unlock

📄 Reference: Unlock Check

{
  "Message": "The message you will specify",
  "not_allowed_actions": ["add_item", "add_discount", "cancel_item", "remove_discount"]
}

With a request sent this way, when the check is unlocked, the cashier will not be able to perform the specified operations.

Example Response — GET Check

📄 Reference: Get Check

Example response for a check returned by the GET Check method, using the id value returned in check_id:

{
  "alias": null,
  "id": "01998af8-6a99-7c3a-a1fe-3218a91ea6b0",
  "created_at": 1758973160,
  "updated_at": 1758973561,
  "business_date": "2025-09-27",
  "closed_at": null,
  "female_cover": 0,
  "male_cover": 0,
  "child_cover": 0,
  "sequence": 99,
  "status": "open",
  "delivery_status": "deliverable",
  "note": null,
  "sequential_id": 1633040,
  "property_id": "d6555bc5-9f97-44d5-a4e2-e638baafdf8c",
  "delivery": null,
  "extras": {},
  "shift_id": null,
  "summary": {
    "original_items_amount": "150.0",
    "original_taxes_amount": "30.0",
    "complimentaries_amount": "0.0",
    "discounts_amount": "0.0",
    "taxes_amount": "30.0",
    "service_charge_amount": "0.0",
    "paid_amount": "0.0",
    "unpaid_amount": "180.0",
    "paid_service_charge_amount": "0.0",
    "total_amount": "180.0",
    "base_amount": "180.0",
    "offer_amount": "0.0"
  },
  "employee": {
    "id": "939e1c1a-c5ba-48a8-a6e7-e0c3d8b15a5c",
    "first_name": "Yönetici",
    "last_name": "Ark",
    "phone_number": "+905327624084"
  },
  "table": null,
  "revenue_center": {
    "id": "c179643d-03fa-4409-9f2b-965a3dddf79c",
    "name": "Fastfood"
  }
}

Payment Flow#

The check is sent to the 3rd party application#

The 3rd party application adds a payment to the check and unlocks it#

Discount Flow#

The check is sent to the 3rd party application#

The 3rd party application adds a discount to the check and unlocks it#

Add Item Flow#

Cancel Item Flow#

Add / Remove Service Charge on Check Flow#

Add#

Remove#

Add Note to Check Flow#

Restricting Actions via the Unlock Parameter Flow#

Example Response — GET Check#

Payment Flow

The check is sent to the 3rd party application

The 3rd party application adds a payment to the check and unlocks it

Discount Flow

The check is sent to the 3rd party application

The 3rd party application adds a discount to the check and unlocks it

Add Item Flow

Cancel Item Flow

Add / Remove Service Charge on Check Flow

Add

Remove

Add Note to Check Flow

Restricting Actions via the Unlock Parameter Flow

Example Response — GET Check