> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/orders/cash-register-hooks.md).

# Cash Register Hooks

In-store cash register integration hook endpoints

## Retrieve Pre-Order Details for Cash Register

> Returns the full pre-order data for an order number that was previously generated\
> by the \`get\_order\_number\` endpoint.\
> \
> \*\*How It Works:\*\*\
> 1\. Validates the request credentials.\
> 2\. Looks up the pre-order session using the provided order number from cache.\
> 3\. Verifies that the payment option is set and is of cash register type.\
> 4\. Verifies the basket has not changed since the pre-order was created.\
> 5\. Returns the full pre-order details including basket, addresses, shipping, and payment data.\
> \
> \*\*Installment Support:\*\*\
> When installment payments are enabled for the cash register integration and an installment\
> plan is selected on the pre-order, an additional \`card\` object is included in the response\
> with details about the selected card and issuing bank.\
> \
> \*\*Authentication:\*\*\
> Credentials are validated against the \`CASH\_REGISTER\_AUTH\_CONF\` dynamic setting\
> (configurable via Admin Panel → Dynamic Settings).\
> \
> \*\*Error Handling:\*\*\
> On failure, the response contains \`error\_code\` and \`error\_message\`. HTTP status is always 200.\
> \
> \| Error Code | Meaning |\
> \|------------|---------|\
> \| \`"402"\` | Basket has changed since the pre-order was created |\
> \| \`"403"\` | Invalid credentials |\
> \| \`"407"\` | No payment option set on the pre-order |\
> \| \`"408"\` | Payment option is not of cash register type |\
> \| \`"409"\` | Order number is missing from the request |\
> \| \`"410"\` | Order number not found in the active pre-order cache |\
> \| \`"411"\` | Pre-order session not found |

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Cash Register Hooks","description":"In-store cash register integration hook endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/hooks/cash_register/pre_order/":{"post":{"tags":["Cash Register Hooks"],"summary":"Retrieve Pre-Order Details for Cash Register","description":"Returns the full pre-order data for an order number that was previously generated\nby the `get_order_number` endpoint.\n\n**How It Works:**\n1. Validates the request credentials.\n2. Looks up the pre-order session using the provided order number from cache.\n3. Verifies that the payment option is set and is of cash register type.\n4. Verifies the basket has not changed since the pre-order was created.\n5. Returns the full pre-order details including basket, addresses, shipping, and payment data.\n\n**Installment Support:**\nWhen installment payments are enabled for the cash register integration and an installment\nplan is selected on the pre-order, an additional `card` object is included in the response\nwith details about the selected card and issuing bank.\n\n**Authentication:**\nCredentials are validated against the `CASH_REGISTER_AUTH_CONF` dynamic setting\n(configurable via Admin Panel → Dynamic Settings).\n\n**Error Handling:**\nOn failure, the response contains `error_code` and `error_message`. HTTP status is always 200.\n\n| Error Code | Meaning |\n|------------|---------|\n| `\"402\"` | Basket has changed since the pre-order was created |\n| `\"403\"` | Invalid credentials |\n| `\"407\"` | No payment option set on the pre-order |\n| `\"408\"` | Payment option is not of cash register type |\n| `\"409\"` | Order number is missing from the request |\n| `\"410\"` | Order number not found in the active pre-order cache |\n| `\"411\"` | Pre-order session not found |","operationId":"getCashRegisterPreOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashRegisterPreOrderRequest"}}}},"responses":{"200":{"description":"Pre-order details on success, or an error response if validation fails.\nCheck for the presence of `error_code` to determine if the request succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashRegisterPreOrderResponse"}}}}}}}},"components":{"schemas":{"CashRegisterPreOrderRequest":{"type":"object","required":["order_number","username","password"],"properties":{"order_number":{"type":"string","description":"Order number previously generated by the `get_order_number` endpoint."},"username":{"type":"string","description":"Integration username for authenticating the cash register request."},"password":{"type":"string","description":"Integration password for authenticating the cash register request."}}},"CashRegisterPreOrderResponse":{"type":"object","description":"On success, contains `order_number` and `pre_order` (plus optional `card`).\nOn failure, contains `error_code` and `error_message`.","properties":{"order_number":{"type":"string","description":"The order number from the request. Present on success only."},"pre_order":{"type":"object","description":"Full pre-order details including basket contents, addresses, payment and shipping options,\namounts, and additional data stored on the pre-order.","additionalProperties":true,"properties":{"basket":{"type":"object","description":"The basket associated with this pre-order.","additionalProperties":true},"shipping_address":{"type":"object","description":"Selected shipping address. Null if not yet set.","nullable":true},"billing_address":{"type":"object","description":"Selected billing address. Null if not yet set.","nullable":true},"payment_option":{"type":"object","description":"Selected payment option. Null if not yet set.","nullable":true},"shipping_option":{"type":"object","description":"Selected shipping option. Null if not yet set.","nullable":true},"shipping_amount":{"type":"string","format":"decimal","description":"Calculated shipping cost.","nullable":true},"total_amount":{"type":"string","format":"decimal","description":"Total order amount including shipping.","nullable":true},"unpaid_amount":{"type":"string","format":"decimal","description":"Outstanding amount to be paid.","nullable":true},"currency_type_label":{"type":"string","description":"Human-readable currency label."}}},"card":{"type":"object","description":"Present only when installment payments are enabled for the cash register integration\nand an installment plan is selected on the pre-order.","properties":{"card_payment_type":{"type":"string","description":"Type of card payment (e.g., credit, debit)."},"name":{"type":"string","description":"Card product name."},"slug":{"type":"string","description":"Card slug identifier."},"bank":{"type":"object","properties":{"name":{"type":"string","description":"Issuing bank name."},"slug":{"type":"string","description":"Issuing bank slug."}}}}},"error_code":{"type":"string","description":"Error code when the request fails. Not present on success."},"error_message":{"type":"string","description":"Human-readable error description. Not present on success."}}}}}}
```

## Generate Cash Register Order Number

> Generates a unique order number for the active basket and registers it\
> in the pre-order session cache for subsequent cash register payment steps.\
> \
> \*\*How It Works:\*\*\
> 1\. Generates a unique order number.\
> 2\. Retrieves the pre-order session linked to the current basket.\
> 3\. Validates that a cash register payment option is selected on the pre-order.\
> 4\. Stores the order number to pre-order mapping in cache (valid for 24 hours).\
> 5\. Returns the generated order number for use in the \`pre\_order\` and \`complete\` steps.\
> \
> \*\*Error Handling:\*\*\
> On error, an \`error\_code\` field is included in the response alongside \`error\_message\`.\
> The HTTP status code is always 200 — check for the presence of \`error\_code\` to detect failures.\
> \
> \| Error Code | Meaning |\
> \|------------|---------|\
> \| \`"407"\` | No payment option is set on the pre-order |\
> \| \`"408"\` | Payment option is not of cash register type |

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Cash Register Hooks","description":"In-store cash register integration hook endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/hooks/cash_register/get_order_number/":{"get":{"tags":["Cash Register Hooks"],"summary":"Generate Cash Register Order Number","description":"Generates a unique order number for the active basket and registers it\nin the pre-order session cache for subsequent cash register payment steps.\n\n**How It Works:**\n1. Generates a unique order number.\n2. Retrieves the pre-order session linked to the current basket.\n3. Validates that a cash register payment option is selected on the pre-order.\n4. Stores the order number to pre-order mapping in cache (valid for 24 hours).\n5. Returns the generated order number for use in the `pre_order` and `complete` steps.\n\n**Error Handling:**\nOn error, an `error_code` field is included in the response alongside `error_message`.\nThe HTTP status code is always 200 — check for the presence of `error_code` to detect failures.\n\n| Error Code | Meaning |\n|------------|---------|\n| `\"407\"` | No payment option is set on the pre-order |\n| `\"408\"` | Payment option is not of cash register type |","operationId":"getCashRegisterOrderNumber","responses":{"200":{"description":"Order number generated and cached, or an error if the pre-order state is invalid.\nCheck for the presence of `error_code` to determine if the request succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashRegisterOrderNumberResponse"}}}}}}}},"components":{"schemas":{"CashRegisterOrderNumberResponse":{"type":"object","description":"Response from the order number generation endpoint.\nOn success, only `order_number` is present.\nOn failure, `error_code` and `error_message` are present; `order_number` may or may not be included.","properties":{"order_number":{"type":"string","description":"Generated unique order number. Present on success and on error_code 408."},"error_code":{"type":"string","description":"Error code when the pre-order state is invalid.\n- `\"407\"`: No payment option set.\n- `\"408\"`: Payment option is not cash register type."},"error_message":{"type":"string","description":"Human-readable error description. Only present on failure."}}}}}}
```

## Complete Cash Register Payment

> Finalizes a cash register payment and schedules order creation.\
> \
> \*\*How It Works:\*\*\
> 1\. Validates the request credentials and order number.\
> 2\. Retrieves the pre-order session associated with the order number.\
> 3\. Verifies that the selected payment option is of cash register type.\
> 4\. Optionally applies promotions to the basket before calculating the amount.\
> 5\. Confirms the submitted amount matches the outstanding balance on the pre-order.\
> 6\. Verifies the basket has not changed since the pre-order was created.\
> 7\. Records the transaction and schedules order completion in the background.\
> \
> \*\*Promotions:\*\*\
> If \`promotions\` is provided, discounts are applied to the basket and the\
> \`discounted\_amount\` field is used for balance validation instead of \`amount\`.\
> \
> \*\*Authentication:\*\*\
> The \`username\` and \`password\` fields are validated against the \`CASH\_REGISTER\_AUTH\_CONF\`\
> dynamic setting (configurable via Admin Panel → Dynamic Settings).\
> \
> \*\*Result Codes:\*\*\
> \
> \| Code | Meaning |\
> \|------|---------|\
> \| \`"0"\` | Payment accepted, order creation scheduled |\
> \| \`402\` | Invalid request payload or basket has changed since pre-order |\
> \| \`403\` | Invalid credentials |\
> \| \`404\` | Order number not found in the active pre-order cache |\
> \| \`405\` | Submitted amount does not match the outstanding balance |\
> \| \`407\` | No payment option is set on the pre-order |\
> \| \`408\` | Payment option is not of cash register type |\
> \| \`411\` | Pre-order session not found |\
> \| \`412\` | Error occurred while applying offer: \<exception text> |\
> \
> \*\*Note:\*\* This endpoint always returns HTTP 200. Both success and failure\
> responses share the same structure — use the \`result\` field to distinguish them.

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Cash Register Hooks","description":"In-store cash register integration hook endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/hooks/cash_register/complete/":{"post":{"tags":["Cash Register Hooks"],"summary":"Complete Cash Register Payment","description":"Finalizes a cash register payment and schedules order creation.\n\n**How It Works:**\n1. Validates the request credentials and order number.\n2. Retrieves the pre-order session associated with the order number.\n3. Verifies that the selected payment option is of cash register type.\n4. Optionally applies promotions to the basket before calculating the amount.\n5. Confirms the submitted amount matches the outstanding balance on the pre-order.\n6. Verifies the basket has not changed since the pre-order was created.\n7. Records the transaction and schedules order completion in the background.\n\n**Promotions:**\nIf `promotions` is provided, discounts are applied to the basket and the\n`discounted_amount` field is used for balance validation instead of `amount`.\n\n**Authentication:**\nThe `username` and `password` fields are validated against the `CASH_REGISTER_AUTH_CONF`\ndynamic setting (configurable via Admin Panel → Dynamic Settings).\n\n**Result Codes:**\n\n| Code | Meaning |\n|------|---------|\n| `\"0\"` | Payment accepted, order creation scheduled |\n| `402` | Invalid request payload or basket has changed since pre-order |\n| `403` | Invalid credentials |\n| `404` | Order number not found in the active pre-order cache |\n| `405` | Submitted amount does not match the outstanding balance |\n| `407` | No payment option is set on the pre-order |\n| `408` | Payment option is not of cash register type |\n| `411` | Pre-order session not found |\n| `412` | Error occurred while applying offer: <exception text> |\n\n**Note:** This endpoint always returns HTTP 200. Both success and failure\nresponses share the same structure — use the `result` field to distinguish them.","operationId":"completeCashRegisterPayment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashRegisterCompleteRequest"}}}},"responses":{"200":{"description":"Response for both successful and failed transactions.\nCheck the `result` field: `\"0\"` indicates success; any other value is an error code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashRegisterCompleteResponse"}}}}}}}},"components":{"schemas":{"CashRegisterCompleteRequest":{"type":"object","required":["transaction_id","order_number","username","password","amount"],"properties":{"transaction_id":{"type":"string","description":"Unique transaction identifier assigned by the cash register terminal."},"order_number":{"type":"string","description":"The order number associated with the active pre-order session."},"username":{"type":"string","description":"Integration username for authenticating the cash register request."},"password":{"type":"string","description":"Integration password for authenticating the cash register request."},"amount":{"type":"string","format":"decimal","description":"Total amount to be paid. Must match the outstanding balance on the pre-order.\nUsed for validation unless `promotions` are provided, in which case\n`discounted_amount` is used instead."},"discounted_amount":{"type":"string","format":"decimal","description":"Discounted total after promotions are applied. Required when `promotions` is provided.\nUsed for balance validation instead of `amount`."},"terminal_code":{"type":"string","description":"Identifier of the cash register terminal. Optional."},"promotions":{"type":"array","description":"Promotions to apply to the basket before completing the payment.\nWhen provided, `discounted_amount` is used for amount validation.","items":{"$ref":"#/components/schemas/CashRegisterPromotion"}}}},"CashRegisterPromotion":{"type":"object","required":["benefit_amount"],"properties":{"benefit_amount":{"type":"string","format":"decimal","description":"Discount amount to apply."},"description":{"type":"string","maxLength":512,"description":"Description of the promotion. Defaults to \"Cash Register Offer\" if not provided."},"affected_basket_items":{"type":"array","description":"IDs of basket items to which this promotion applies. Defaults to all items if empty.","items":{"type":"integer"}}}},"CashRegisterCompleteResponse":{"type":"object","description":"Returned for both successful and failed cash register payment completions.\nThe `result` field indicates the outcome.","properties":{"transaction_id":{"type":["string","null"],"description":"Transaction identifier from the request. `null` on failure."},"order_number":{"type":["string","null"],"description":"Order number from the request. `null` when the order was not resolved."},"result":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"`\"0\"` on success. Integer error code on failure:\n402 (invalid input or basket changed), 403 (invalid credentials),\n404 (order not found), 405 (amount mismatch), 407 (payment option not set),\n408 (wrong payment option type), 411 (pre-order not found), 412 (offer application error)."},"error_message":{"type":"string","description":"Human-readable error description. Empty string on success."},"amount":{"type":["string","null"],"format":"decimal","description":"Confirmed payment amount. `null` on failure."},"staff_id":{"type":["integer","null"],"description":"Staff member identifier from the pre-order. `null` on failure."},"staff_email":{"type":["string","null"],"description":"Email of the staff member associated with the pre-order. `null` on failure."},"store_id":{"type":["string","null"],"description":"Store identifier from the pre-order. `null` on failure."},"shipping_sku":{"type":["string","null"],"description":"SKU of the configured shipping product for cash register payments.\n`null` if not configured or on failure."}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://apidocs.akinon.com/commerce-openapis/orders/cash-register-hooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.