API reference · Nexus Gateway

Explore the exact contract served by this gateway. Types, constraints and examples below come from its OpenAPI schema.

Use your website key. Menu publishing uses a separate operator credential. Examples are synthetic; no request is sent from this page.

Download OpenAPI 3.1 ↗

GET/health

Check process liveness

Authentication: No authentication

Returns 200 while the gateway process is running. Needs no key. It doesn't check menus or the restaurant's systems.

Responses

200

The gateway process is running.

object

Request

cURL

curl "https://website.api.pionier.ro/health"

Response

200

No content

GET/v1/connections

Discover enabled points of sale

Authentication: WebsiteKey

Lists the locations and registers that can receive orders with your website key. Use a connection's id in every menu, order and status request, even when there is only one. An empty list means the restaurant hasn't enabled website ordering yet.

Responses

200

Connections enabled for your website key.

ConnectionList

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

503

Outcome unconfirmed. Retry after at least 5 seconds; preserve order ID and body.

Error | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl "https://website.api.pionier.ro/v1/connections" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Response

200

No content

401

{
  "detail": "invalid_credentials"
}

503

{
  "error": "storage_unavailable"
}

429

{
  "error": "rate_limit_exceeded"
}

GET/v1/connections/{connection_id}/menu

Read the restaurant menu

Authentication: WebsiteKey

Returns the menu published for this connection. Amounts are integer bani. Send the revision and IDs from this menu in the order. Availability and accepting_orders can change without a new revision, so fetch the menu again just before checkout.

Parameters

connection_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

fulfillment_atstring | nullqueryoptional

Responses

200

The published menu for this connection.

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

404

Connection unavailable to this tenant, or the requested menu/order does not exist.

DetailError

409

Conflict, such as an outdated menu revision or a sold-out item. The error code says what to change.

Error

503

Outcome unconfirmed. Retry after at least 5 seconds; preserve order ID and body.

Error | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/menu" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Response

200

{
  "revision": "example-menu-1",
  "currency": "RON",
  "accepting_orders": true,
  "fulfillment": [
    "pickup",
    "delivery"
  ],
  "delivery_fee": 700,
  "categories": [
    {
      "id": "pizzas",
      "name": "Pizza"
    },
    {
      "id": "meals",
      "name": "Meals"
    }
  ],
  "products": [
    {
      "id": "pizza-margherita",
      "category_id": "pizzas",
      "name": "Margherita",
      "description": "Tomato, mozzarella and basil",
      "image_url": "https://images.example.test/margherita.jpg",
      "translations": {
        "en": {
          "name": "Margherita",
          "description": "Tomato, mozzarella and basil"
        },
        "ro": {
          "name": "Margherita",
          "description": "Roșii, mozzarella și busuioc"
        }
      },
      "price": 3200,
      "packaging": 100,
      "packaging_product_id": "pizza-box",
      "modifier_groups": [
        {
          "id": "pizza-extras",
          "name": "Extras",
          "kind": "extra",
          "minimum": 0,
          "maximum": 1,
          "options": [
            {
              "id": "cheese",
              "name": "Extra cheese",
              "price": 400
            }
          ]
        }
      ]
    },
    {
      "id": "burger-meal",
      "category_id": "meals",
      "name": "Burger meal",
      "description": "Burger, fries and your choice of drink",
      "translations": {
        "en": {
          "name": "Burger meal",
          "description": "Burger, fries and your choice of drink"
        },
        "ro": {
          "name": "Meniu burger",
          "description": "Burger, cartofi prăjiți și băutură la alegere"
        }
      },
      "price": 2500,
      "packaging": 100,
      "packaging_product_id": "meal-bag",
      "modifier_groups": [
        {
          "id": "size",
          "name": "Size",
          "kind": "variant",
          "minimum": 1,
          "maximum": 1,
          "options": [
            {
              "id": "regular",
              "name": "Regular",
              "price": 0
            },
            {
              "id": "large",
              "name": "Large",
              "price": 0
            }
          ]
        },
        {
          "id": "drink",
          "name": "Drink",
          "kind": "bundle",
          "minimum": 1,
          "maximum": 1,
          "options": [
            {
              "id": "water",
              "name": "Water",
              "price": 0,
              "deposit": 50
            }
          ]
        },
        {
          "id": "meal-extras",
          "name": "Extras",
          "kind": "extra",
          "minimum": 0,
          "maximum": 1,
          "options": [
            {
              "id": "sauce",
              "name": "Extra sauce",
              "price": 200
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "meal-regular",
          "selections": [
            {
              "group_id": "size",
              "option_id": "regular"
            }
          ],
          "price": 2500
        },
        {
          "id": "meal-large",
          "selections": [
            {
              "group_id": "size",
              "option_id": "large"
            }
          ],
          "price": 3000
        }
      ]
    }
  ]
}

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "menu_not_published"
}

409

{
  "error": "scheduled_time_unavailable"
}

503

{
  "error": "storage_unavailable"
}

429

{
  "error": "rate_limit_exceeded"
}

PUT/v1/menu

Publish a complete menu

Authentication: PublisherKey

Used by Nexus Retail with a publisher key; website integrations never call it. Revisions are immutable. Include the required positive X-Website-Publication generation. An identical retry with the same generation is idempotent unless a newer generation has arrived; obsolete generations or changed contents under the same generation return 409 publication_superseded.

Parameters

x-website-publicationintegerheaderrequired

min: 1 · max: 9223372036854775807

Request body application/json

Schema: Menu

revisionstringrequired

Version of the published menu. Send it as menu_revision. Availability and accepting_orders can change without a new revision.

min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

currencystringoptional

Always RON. Amounts are integer bani.

default: "RON" · value: "RON"

accepting_ordersbooleanoptional

False while the restaurant is paused or closed. Keep showing the menu but disable checkout.

default: true

opening_hoursOpeningHours | nulloptional

Current restaurant hours and date exceptions in its local time zone. Null when no policy is configured.

schedulingSchedulingPolicyoptional

Scheduled orders are always supported; default preparation duration controls kitchen timing.

fulfillmentarray<string>required

Always includes pickup and delivery.

min items: 1 · max items: 2

delivery_feeintegeroptional

Fixed fee in bani, charged once per delivery order and never for pickup.

min: 0.0 · max: 100000000.0 · default: 0

tips_enabledbooleanoptional

Whether restaurant staff tips can be included. Requires the POS tip configuration; courier tips are not included.

default: false

categoriesarray<Category>required

Menu sections.

min items: 1 · max items: 200

productsarray<Product>required

Everything that can be ordered. Each product references a category.

min items: 1 · max items: 5000

Responses

204

The menu was published, or an identical copy was already published.

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

409

Conflict, such as an outdated menu revision or a sold-out item. The error code says what to change.

Error

413

Request body exceeds 4 MiB.

Error

503

Outcome unconfirmed. Retry after at least 5 seconds; preserve order ID and body.

Error | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl -X PUT "https://website.api.pionier.ro/v1/menu" \
  -H "Authorization: Bearer $NEXUS_PUBLISHER_KEY" \
  -H "X-Website-Publication: 1" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

request.json

{
  "revision": "example-menu-1",
  "currency": "RON",
  "accepting_orders": true,
  "fulfillment": [
    "pickup",
    "delivery"
  ],
  "delivery_fee": 700,
  "categories": [
    {
      "id": "pizzas",
      "name": "Pizza"
    },
    {
      "id": "meals",
      "name": "Meals"
    }
  ],
  "products": [
    {
      "id": "pizza-margherita",
      "category_id": "pizzas",
      "name": "Margherita",
      "description": "Tomato, mozzarella and basil",
      "image_url": "https://images.example.test/margherita.jpg",
      "translations": {
        "en": {
          "name": "Margherita",
          "description": "Tomato, mozzarella and basil"
        },
        "ro": {
          "name": "Margherita",
          "description": "Roșii, mozzarella și busuioc"
        }
      },
      "price": 3200,
      "packaging": 100,
      "packaging_product_id": "pizza-box",
      "modifier_groups": [
        {
          "id": "pizza-extras",
          "name": "Extras",
          "kind": "extra",
          "minimum": 0,
          "maximum": 1,
          "options": [
            {
              "id": "cheese",
              "name": "Extra cheese",
              "price": 400
            }
          ]
        }
      ]
    },
    {
      "id": "burger-meal",
      "category_id": "meals",
      "name": "Burger meal",
      "description": "Burger, fries and your choice of drink",
      "translations": {
        "en": {
          "name": "Burger meal",
          "description": "Burger, fries and your choice of drink"
        },
        "ro": {
          "name": "Meniu burger",
          "description": "Burger, cartofi prăjiți și băutură la alegere"
        }
      },
      "price": 2500,
      "packaging": 100,
      "packaging_product_id": "meal-bag",
      "modifier_groups": [
        {
          "id": "size",
          "name": "Size",
          "kind": "variant",
          "minimum": 1,
          "maximum": 1,
          "options": [
            {
              "id": "regular",
              "name": "Regular",
              "price": 0
            },
            {
              "id": "large",
              "name": "Large",
              "price": 0
            }
          ]
        },
        {
          "id": "drink",
          "name": "Drink",
          "kind": "bundle",
          "minimum": 1,
          "maximum": 1,
          "options": [
            {
              "id": "water",
              "name": "Water",
              "price": 0,
              "deposit": 50
            }
          ]
        },
        {
          "id": "meal-extras",
          "name": "Extras",
          "kind": "extra",
          "minimum": 0,
          "maximum": 1,
          "options": [
            {
              "id": "sauce",
              "name": "Extra sauce",
              "price": 200
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "meal-regular",
          "selections": [
            {
              "group_id": "size",
              "option_id": "regular"
            }
          ],
          "price": 2500
        },
        {
          "id": "meal-large",
          "selections": [
            {
              "group_id": "size",
              "option_id": "large"
            }
          ],
          "price": 3000
        }
      ]
    }
  ]
}

Response

204

No content

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

409

{
  "error": "revision_already_used"
}

413

{
  "error": "body_too_large"
}

503

{
  "error": "storage_unavailable"
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/connections/{connection_id}/orders

Submit an order

Authentication: WebsiteKey

Sends an order to the restaurant. 201 means the restaurant received it; staff still have to accept it. Resending the identical request returns 200 with the original receipt and never creates a second order. After a timeout or 503, resend the same external_order_id and body. Receive progress through webhooks; use GET to reconcile missed updates or when webhooks are unavailable.

Parameters

connection_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

Request body application/json

Schema: OrderRequest

external_order_idstringrequired

Your ID for this purchase. Save it before sending and reuse it unchanged on every retry; the gateway never creates two orders for one ID.

min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

menu_revisionstringrequired

The revision of the menu used to price this cart.

min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

currencystringoptional

Always RON.

default: "RON" · value: "RON"

fulfillmentstringrequired

pickup or delivery. Both modes are supported.

values: ["delivery", "pickup"]

scheduled_forstring | nulloptional

Requested fulfillment timestamp with explicit offset. Null means immediate fulfillment.

customerCustomerrequired

Who placed the order.

addressAddress | nulloptional

Required for delivery; omit or send null for pickup.

paymentPaymentrequired

How the order is paid. Nexus doesn't charge the customer.

itemsarray<OrderLine>required

The cart: 1 to 100 lines.

min items: 1 · max items: 100

totalintegerrequired

Your calculated total in bani, after published discounts and including deposits, packaging, delivery fee and tip. The gateway recalculates and rejects a mismatch.

min: 0.0 · max: 100000000.0

tipintegeroptional

Optional restaurant staff tip in bani, default zero. Include it once in total. Requires menu.tips_enabled.

min: 0.0 · max: 100000000.0 · default: 0

checkout_discountCheckoutDiscount | nulloptional

Optional checkout coupon. One per order; allocation is frozen with the original request.

notesstringoptional

Instructions for the whole order. Use items[].notes for a single product.

max length: 1000 · default: ""

Responses

201

The restaurant received the order; it is waiting for staff to accept it.

OrderReceipt

200

The identical order was already received; returns its original receipt.

OrderReceipt

409

Conflict, such as an outdated menu revision or a sold-out item. The error code says what to change.

Error

503

Outcome unconfirmed. Retry after at least 5 seconds; preserve order ID and body.

Error | objectHeader Retry-After Minimum delay in seconds.

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

413

Request body exceeds 4 MiB.

Error

404

Connection unavailable to this tenant, or the requested menu/order does not exist.

DetailError

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl -X POST "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Pizza pickup, paid online

{
  "external_order_id": "shop-1001",
  "menu_revision": "example-menu-1",
  "currency": "RON",
  "fulfillment": "pickup",
  "customer": {
    "name": "Example Customer",
    "phone": "0700000000"
  },
  "payment": {
    "method": "paid_online",
    "reference": "payment-example-1001"
  },
  "items": [
    {
      "product_id": "pizza-margherita",
      "quantity": 1,
      "modifiers": [
        {
          "group_id": "pizza-extras",
          "option_id": "cheese"
        }
      ],
      "notes": "Please slice the pizza"
    }
  ],
  "total": 3700,
  "notes": "Pickup by Alex"
}

Two bundle meals, cash on delivery

{
  "external_order_id": "shop-1002",
  "menu_revision": "example-menu-1",
  "currency": "RON",
  "fulfillment": "delivery",
  "customer": {
    "name": "Example Customer",
    "phone": "0700000000"
  },
  "address": {
    "city": "Iași",
    "street": "Example Street 10",
    "details": "Apartment 2, ring the bell"
  },
  "payment": {
    "method": "cash_on_fulfillment"
  },
  "items": [
    {
      "product_id": "burger-meal",
      "quantity": 2,
      "modifiers": [
        {
          "group_id": "size",
          "option_id": "large"
        },
        {
          "group_id": "drink",
          "option_id": "water"
        },
        {
          "group_id": "meal-extras",
          "option_id": "sauce"
        }
      ]
    }
  ],
  "total": 7400
}

Response

201

{
  "external_order_id": "shop-1001",
  "status": "pending_acceptance",
  "total": 3700,
  "currency": "RON"
}

200

{
  "external_order_id": "shop-1001",
  "status": "pending_acceptance",
  "total": 3700,
  "currency": "RON"
}

409

{
  "error": "menu_changed"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

413

{
  "error": "body_too_large"
}

404

{
  "detail": "connection_not_found"
}

429

{
  "error": "rate_limit_exceeded"
}

GET/v1/connections/{connection_id}/orders/{external_order_id}

Read current order status

Authentication: WebsiteKey

Returns the order's current status from the restaurant. Use it to reconcile webhook notifications or poll when webhooks are not configured. A 503 means the status couldn't be read, not that the order was rejected. Stop polling on completed, rejected or cancelled.

Parameters

connection_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

external_order_idstringpathrequired

min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

Responses

200

The order's current status.

OrderReceipt

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

404

Connection unavailable to this tenant, or the requested menu/order does not exist.

DetailError

503

Outcome unconfirmed. Retry after at least 5 seconds; preserve order ID and body.

Error | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders/shop-1001" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Response

200

{
  "external_order_id": "shop-1001",
  "status": "accepted",
  "total": 3700,
  "currency": "RON"
}

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "order_not_found"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/connections/{connection_id}/orders/{external_order_id}/refunds

Report an external refund outcome

Authentication: WebsiteKey

Record a final succeeded or failed refund performed by your payment provider. This does not initiate or verify a refund and does not reverse a Retail receipt. Only paid_online orders are eligible. Save request_id and retry the identical body after an uncertain response. Each processor_reference is unique per order; at most 100 reports. Successful amounts cannot exceed the original order total.

Parameters

connection_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

external_order_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

Request body application/json

Schema: RefundReport

request_idstringrequired

Stable identity for this final refund report; retry unchanged.

min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

processor_referencestringrequired

Unique processor reference per order; retained privately for reconciliation.

min length: 1 · max length: 200

outcomestringrequired

Final outcome reported by your website: succeeded or failed. Not verified with a processor.

values: ["succeeded", "failed"]

amountintegerrequired

Positive refund amount in bani, excluding refunds already reported.

min: 1.0 · max: 100000000.0

Responses

200

Successful Response

OrderReceipt

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

404

Connection unavailable to this tenant, or the requested menu/order does not exist.

DetailError

409

Conflict, such as an outdated menu revision or a sold-out item. The error code says what to change.

Error

503

Outcome unconfirmed. Retry after at least 5 seconds; preserve order ID and body.

Error | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl -X POST "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders/shop-1001/refunds" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Response

200

No content

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "order_not_found"
}

409

{
  "error": "refund_report_not_allowed"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/connections/{connection_id}/orders/{external_order_id}/delivery

Report delivery progress

Authentication: WebsiteKey

Send a stable request_id for each update and retry its unchanged body after an uncertain result. Delivery orders only: assignment requires acceptance, pickup requires ready, and delivered requires picked_up. At most 100 distinct updates per order. Omitted contact details and estimates preserve previous values. This never records payment collection.

Parameters

connection_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

external_order_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

Request body application/json

Schema: DeliveryUpdate

request_idstringrequired

Stable identity for this delivery update; retry unchanged.

min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

statusstringrequired

assigned, arrived, picked_up or delivered; transitions cannot move backwards.

values: ["assigned", "arrived", "picked_up", "delivered"]

courier_namestring | nulloptional

Courier name for restaurant staff; excluded from public status and webhooks.

courier_phonestring | nulloptional

Courier phone for restaurant staff; excluded from public status and webhooks.

estimated_pickup_atstring | nulloptional

Estimated pickup timestamp with offset; null preserves the previous estimate.

estimated_delivery_atstring | nulloptional

Estimated delivery timestamp with offset; null preserves the previous estimate.

Responses

200

Successful Response

OrderReceipt

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

404

Connection unavailable to this tenant, or the requested menu/order does not exist.

DetailError

409

Conflict, such as an outdated menu revision or a sold-out item. The error code says what to change.

Error

503

Outcome unconfirmed. Retry after at least 5 seconds; preserve order ID and body.

Error | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl -X POST "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders/shop-1001/delivery" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Response

200

No content

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "order_not_found"
}

409

{
  "error": "delivery_update_not_allowed"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/connections/{connection_id}/orders/{external_order_id}/cancel

Cancel an eligible order

Authentication: WebsiteKey

Immediate orders can be cancelled before acceptance. Accepted scheduled orders can be cancelled strictly before their persisted preparation start, provided preparation has not begun. Later cancellation requires restaurant staff approval in Retail; completed orders cannot be cancelled. Retry the identical request_id and body after an uncertain response. A 409 cancellation_not_allowed means the order is outside the customer cancellation window or no longer eligible. Cancellation does not refund payment or reverse fiscal receipts; staff must reconcile existing receipts in Nexus ERP.

Parameters

connection_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

external_order_idstringpathrequired

pattern: "^[A-Za-z0-9_-]{1,100}$"

Request body application/json

Schema: CancellationRequest

request_idstringrequired

Stable cancellation identity. Save and resend the same ID and reason after uncertain outcomes.

min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

reasonstringrequired

Customer cancellation reason. This never initiates a refund.

values: ["customer_request", "duplicate", "ordered_by_mistake", "other"]

Responses

200

Successful Response

OrderReceipt

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

404

Connection unavailable to this tenant, or the requested menu/order does not exist.

DetailError

409

Conflict, such as an outdated menu revision or a sold-out item. The error code says what to change.

Error

503

Outcome unconfirmed. Retry after at least 5 seconds; preserve order ID and body.

Error | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl -X POST "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders/shop-1001/cancel" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Response

200

No content

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "order_not_found"
}

409

{
  "error": "cancellation_not_allowed"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

429

{
  "error": "rate_limit_exceeded"
}

GET/v1/webhook

Read webhook configuration

Authentication: WebsiteKey

Returns this tenant's callback configuration. The signing secret is never returned by GET. One callback serves every enabled POS connection.

Responses

200

Current callback configuration; save any returned signing secret securely.

WebhookSubscription

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

503

Webhook signing is not enabled on this gateway. Contact Nexus; existing order routes remain available.

DetailError | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl "https://website.api.pionier.ro/v1/webhook" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Response

200

No content

401

{
  "detail": "invalid_credentials"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

PUT/v1/webhook

Configure a tenant webhook

Authentication: WebsiteKey

Register one public HTTPS callback on port 443 using your website key. Set enabled to false to stop delivery. Creating or changing the URL returns a new signing_secret once and cancels queued events for the old configuration. An identical PUT preserves the secret and returns null for signing_secret; rotate it if the initial response was lost. New orders received while enabled are watched in the background; existing order history is not backfilled.

Request body application/json

Schema: WebhookConfiguration

urlstringrequired

Public HTTPS callback URL on port 443. No query, fragment or credentials.

max length: 2048

enabledbooleanoptional

Enable order, availability, menu and connection notifications. False cancels queued deliveries.

default: true

Responses

200

Current callback configuration; save any returned signing secret securely.

WebhookSubscription

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

503

Webhook signing is not enabled on this gateway. Contact Nexus; existing order routes remain available.

DetailError | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl -X PUT "https://website.api.pionier.ro/v1/webhook" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

request.json

{
  "url": "https://shop.example.com/nexus/events",
  "enabled": true
}

Response

200

No content

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/webhook/rotate-secret

Rotate the webhook signing secret

Authentication: WebsiteKey

Returns a new signing secret for the current callback. Queued events signed for the previous configuration are cancelled. An in-flight HTTP request can still arrive. API key rotation is separate and does not change this secret.

Responses

200

Current callback configuration; save any returned signing secret securely.

WebhookSubscription

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

404

See the error code and recovery guide.

DetailError

503

Webhook signing is not enabled on this gateway. Contact Nexus; existing order routes remain available.

DetailError | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl -X POST "https://website.api.pionier.ro/v1/webhook/rotate-secret" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Response

200

No content

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "webhook_not_configured"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

GET/v1/webhook/deliveries

Inspect recent webhook deliveries

Authentication: WebsiteKey

Returns up to 100 recent deliveries for this tenant, newest first. Includes stable event IDs, order/connection IDs, attempt counts, delivery state and sanitized failure codes. Receiver response bodies and signing secrets are never exposed.

Responses

200

Latest 100 delivery records for this tenant.

array<WebhookDelivery>

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

503

Webhook signing is not enabled on this gateway. Contact Nexus; existing order routes remain available.

DetailError | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl "https://website.api.pionier.ro/v1/webhook/deliveries" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Response

200

No content

401

{
  "detail": "invalid_credentials"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/webhook/deliveries/{event_id}/retry

Retry an exhausted delivery

Authentication: WebsiteKey

Requeues a failed event with the same event ID and body, with a fresh delivery attempt window. Only this tenant's failed events for the current enabled callback can be retried. The original per-order sequence remains unchanged; receivers must ignore older sequences.

Parameters

event_idstringpathrequired

pattern: "^evt_[a-f0-9]{48}$"

Responses

204

The failed event was requeued with its original identity and body.

422

Invalid input. Field paths and types are returned; input values are omitted.

ValidationError

401

Missing, invalid or wrong-role key.

DetailErrorHeader WWW-Authenticate

404

See the error code and recovery guide.

DetailError

503

Webhook signing is not enabled on this gateway. Contact Nexus; existing order routes remain available.

DetailError | objectHeader Retry-After Minimum delay in seconds.

429

Rate limit exceeded. Wait Retry-After seconds and retry the identical request.

Header Retry-After Seconds to wait.

Request

cURL

curl -X POST "https://website.api.pionier.ro/v1/webhook/deliveries/$NEXUS_EVENT_ID/retry" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Response

204

No content

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "failed_delivery_not_found"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

Data models

Unknown request fields are rejected. Monetary amounts are integer bani; quantities are integers. Conditional requirements such as delivery addresses and payment references are described in the guides.

Address

Field	Contract
`city`required	string Delivery city. min length: 1 · max length: 100
`street`required	string Street and number. min length: 1 · max length: 200
`details`optional	string Apartment, entrance or other directions. max length: 500 · default: ""

CancellationRequest

Field	Contract
`request_id`required	string Stable cancellation identity. Save and resend the same ID and reason after uncertain outcomes. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`reason`required	string Customer cancellation reason. This never initiates a refund. values: ["customer_request", "duplicate", "ordered_by_mistake", "other"]

Category

Field	Contract
`name`required	string Section name to show customers. min length: 1 · max length: 256
`translations`optional	object Locale-keyed names and descriptions. Fall back to name and description when a translation is absent.
`id`required	string Category ID referenced by products. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

CheckoutDiscount

Field	Contract
`code`required	string Website coupon identifier; eligibility is checked by the website backend. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`amount`required	integer Restaurant-funded discount in integer bani, after menu promotions. Cannot exceed the eligible product base prices. min: 1.0 · max: 100000000.0
`product_ids`optional	array<string> \| null Optional unique product IDs from this order. Omit for all products. Extras, deposits, packaging, delivery and tips are excluded.

ConnectionList

Field	Contract
`connections`required	array<ConnectionSummary> Connections enabled for your website key. Empty until the restaurant enables one.

ConnectionSummary

Field	Contract
`id`required	string Connection ID to use in menu, order and status URLs. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`location_id`required	string The restaurant location's ID. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`location_name`required	string Location name to show customers.
`pos_id`required	string The receiving register's ID. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`pos_name`required	string Register name, useful for support.

Customer

Field	Contract
`name`required	string Customer name for staff and the receipt. min length: 1 · max length: 200
`phone`required	string Phone number staff can call about the order. min length: 3 · max length: 40

DatePeriod

Field	Contract
`start`required	string Inclusive local start time, HH:mm.
`end`required	string Exclusive end on the same date, HH:mm; 24:00 is allowed.

DeliveryStatus

Field	Contract
`status`required	string Last committed delivery progress. values: ["assigned", "arrived", "picked_up", "delivered"]
`estimated_pickup_at`optional	string \| null Latest pickup estimate, or null.
`estimated_delivery_at`optional	string \| null Latest delivery estimate, or null.
`picked_up_at`optional	string \| null Server timestamp when pickup was recorded.
`delivered_at`optional	string \| null Server timestamp when delivery was recorded.

DeliveryUpdate

Field	Contract
`request_id`required	string Stable identity for this delivery update; retry unchanged. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`status`required	string assigned, arrived, picked_up or delivered; transitions cannot move backwards. values: ["assigned", "arrived", "picked_up", "delivered"]
`courier_name`optional	string \| null Courier name for restaurant staff; excluded from public status and webhooks.
`courier_phone`optional	string \| null Courier phone for restaurant staff; excluded from public status and webhooks.
`estimated_pickup_at`optional	string \| null Estimated pickup timestamp with offset; null preserves the previous estimate.
`estimated_delivery_at`optional	string \| null Estimated delivery timestamp with offset; null preserves the previous estimate.

Field	Contract
`revision`required	string Version of the published menu. Send it as menu_revision. Availability and accepting_orders can change without a new revision. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`currency`optional	string Always RON. Amounts are integer bani. default: "RON" · value: "RON"
`accepting_orders`optional	boolean False while the restaurant is paused or closed. Keep showing the menu but disable checkout. default: true
`opening_hours`optional	OpeningHours \| null Current restaurant hours and date exceptions in its local time zone. Null when no policy is configured.
`scheduling`optional	SchedulingPolicy Scheduled orders are always supported; default preparation duration controls kitchen timing.
`fulfillment`required	array<string> Always includes pickup and delivery. min items: 1 · max items: 2
`delivery_fee`optional	integer Fixed fee in bani, charged once per delivery order and never for pickup. min: 0.0 · max: 100000000.0 · default: 0
`tips_enabled`optional	boolean Whether restaurant staff tips can be included. Requires the POS tip configuration; courier tips are not included. default: false
`categories`required	array<Category> Menu sections. min items: 1 · max items: 200
`products`required	array<Product> Everything that can be ordered. Each product references a category. min items: 1 · max items: 5000

Modifier

Field	Contract
`name`required	string Option name to show customers. min length: 1 · max length: 256
`translations`optional	object Locale-keyed names and descriptions. Fall back to name and description when a translation is absent.
`id`required	string Send as items[].modifiers[].option_id. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`price`required	integer Added price in bani for an extra. Always 0 for variant and bundle options. min: 0.0 · max: 100000000.0
`deposit`optional	integer Deposit in bani added when selected, such as a bottle deposit on an included drink. min: 0.0 · max: 100000000.0 · default: 0
`available`optional	boolean False when sold out. Don't let customers select it. default: true

ModifierGroup

Field	Contract
`name`required	string Group name to show customers. min length: 1 · max length: 256
`translations`optional	object Locale-keyed names and descriptions. Fall back to name and description when a translation is absent.
`kind`optional	string variant defines the product (for example size), bundle is an included item, extra is a paid addition. default: "extra" · values: ["extra", "variant", "bundle"]
`id`required	string Send as items[].modifiers[].group_id. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`minimum`optional	integer Fewest different options the customer must choose. min: 0.0 · max: 99.0 · default: 0
`maximum`optional	integer Most different options the customer may choose. min: 1.0 · max: 99.0 · default: 1
`options`required	array<Modifier> The options in this group. min items: 1 · max items: 100

OpeningHours

Field	Contract
`schedule_enabled`optional	boolean Whether weekly hours restrict ordering. Date exceptions and manual pauses still apply. default: false
`time_zone`optional	string IANA time zone used for restaurant and product hours. default: "Europe/Bucharest"
`periods`optional	array<OpeningPeriod> Weekly opening intervals; overnight intervals are allowed. max items: 28
`special_dates`optional	array<SpecialDate> Whole-day replacements for specific local dates. Empty periods means closed. max items: 366

OpeningPeriod

Field	Contract
`day`required	integer ISO weekday: Monday 1 through Sunday 7. min: 1.0 · max: 7.0
`start`required	string Inclusive local start time, HH:mm.
`end`required	string Exclusive local end time, HH:mm; 24:00 is allowed. An earlier time ends the next day.

OrderLine

Field	Contract
`product_id`required	string A product ID from the menu. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`quantity`required	integer Number of units, 1 to 99. min: 1.0 · max: 99.0
`modifiers`optional	array<Selection> Every option the customer chose for this line, including size and included items. Each pair at most once. max items: 100
`notes`optional	string Instructions for this line, such as 'no onions'. max length: 500 · default: ""

OrderReceipt

Field	Contract
`external_order_id`required	string Your order ID. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`status`required	string The order's progress. On a repeated POST, the status from when the order was first received. values: ["pending_acceptance", "accepted", "preparing", "ready", "out_for_delivery", "completed", "rejected", "cancelled"]
`total`required	integer The order total in bani. min: 0.0 · max: 100000000.0
`currency`required	string Always RON. value: "RON"
`scheduled_for`optional	string \| null Original requested fulfillment timestamp, or null for immediate orders.
`estimated_ready_at`optional	string \| null Restaurant ready estimate after acceptance; may be later than the requested time.
`reason`optional	string \| null Rejection or cancellation reason code, when available.
`delivery`optional	DeliveryStatus \| null Delivery progress and estimates without courier contact details; null until reported.
`refund`optional	RefundStatus \| null External refund reporting summary, or null before the first report.

OrderRequest

Field	Contract
`external_order_id`required	string Your ID for this purchase. Save it before sending and reuse it unchanged on every retry; the gateway never creates two orders for one ID. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`menu_revision`required	string The revision of the menu used to price this cart. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`currency`optional	string Always RON. default: "RON" · value: "RON"
`fulfillment`required	string pickup or delivery. Both modes are supported. values: ["delivery", "pickup"]
`scheduled_for`optional	string \| null Requested fulfillment timestamp with explicit offset. Null means immediate fulfillment.
`customer`required	Customer Who placed the order.
`address`optional	Address \| null Required for delivery; omit or send null for pickup.
`payment`required	Payment How the order is paid. Nexus doesn't charge the customer.
`items`required	array<OrderLine> The cart: 1 to 100 lines. min items: 1 · max items: 100
`total`required	integer Your calculated total in bani, after published discounts and including deposits, packaging, delivery fee and tip. The gateway recalculates and rejects a mismatch. min: 0.0 · max: 100000000.0
`tip`optional	integer Optional restaurant staff tip in bani, default zero. Include it once in total. Requires menu.tips_enabled. min: 0.0 · max: 100000000.0 · default: 0
`checkout_discount`optional	CheckoutDiscount \| null Optional checkout coupon. One per order; allocation is frozen with the original request.
`notes`optional	string Instructions for the whole order. Use items[].notes for a single product. max length: 1000 · default: ""

Payment

Field	Contract
`method`required	string paid_online when your payment provider has already charged the customer; cash_on_fulfillment or card_on_fulfillment when the restaurant collects payment. values: ["paid_online", "cash_on_fulfillment", "card_on_fulfillment"]
`reference`optional	string \| null Your payment provider's transaction reference. Required for paid_online; omit for the other methods.

Product

Field	Contract
`name`required	string Product name to show customers. Render as text. min length: 1 · max length: 256
`translations`optional	object Locale-keyed names and descriptions. Fall back to name and description when a translation is absent.
`id`required	string Send as items[].product_id. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`category_id`required	string The category this product belongs to. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`description`optional	string Optional description to show customers. Render as text. max length: 4000 · default: ""
`image_url`optional	string \| null Optional absolute HTTP(S) image URL. The gateway does not fetch the image.
`schedule`optional	array<OpeningPeriod> \| null Weekly product hours in opening_hours.time_zone. Null is unrestricted; an empty list means unavailable all week.
`price`required	integer Base price in bani. For a product with variants, the selected variant's price replaces it. min: 0.0 · max: 100000000.0
`discount`optional	integer Published discount in bani per unit, subtracted from price before deposits, packaging and extras. Defaults to zero. Never send a discount in an order. min: 0.0 · max: 100000000.0 · default: 0
`deposit`optional	integer Deposit in bani per unit, such as a bottle deposit. A selected variant's deposit replaces it. min: 0.0 · max: 100000000.0 · default: 0
`packaging`optional	integer Packaging charge in bani per unit, added on top of the price. min: 0.0 · max: 100000000.0 · default: 0
`packaging_product_id`optional	string \| null The packaging item the restaurant adds to the receipt. Don't add it to your order.
`available`optional	boolean False when sold out or not sold at this location. Don't let customers select it. default: true
`modifier_groups`optional	array<ModifierGroup> Choices for this product: variant (such as size), bundle (an included item) or extra (a paid addition). max items: 30
`variants`optional	array<Variant> Every valid combination of the product's variant choices, each with its own price. Match the customer's choices to one of them. max items: 500

RefundReport

Field	Contract
`request_id`required	string Stable identity for this final refund report; retry unchanged. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`processor_reference`required	string Unique processor reference per order; retained privately for reconciliation. min length: 1 · max length: 200
`outcome`required	string Final outcome reported by your website: succeeded or failed. Not verified with a processor. values: ["succeeded", "failed"]
`amount`required	integer Positive refund amount in bani, excluding refunds already reported. min: 1.0 · max: 100000000.0

RefundStatus

Field	Contract
`reported_refunded_amount`required	integer Sum of successful refund amounts reported by your website; not processor verification. min: 0.0 · max: 100000000.0
`report_count`required	integer Number of distinct final reports, including failed refunds. min: 1.0 · max: 100.0
`last_outcome`required	string Last reported outcome: succeeded or failed. values: ["succeeded", "failed"]
`last_reported_at`required	string Server timestamp of the most recently committed report.

SchedulingPolicy

Field	Contract
`enabled`optional	boolean Always true. Scheduled orders do not require opt-in. default: true
`preparation_minutes`optional	integer Default preparation duration; staff may add time at acceptance. min: 1.0 · max: 240.0 · default: 20

Selection

Field	Contract
`group_id`required	string A modifier group ID from the product. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`option_id`required	string An option ID from that group. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"

SpecialDate

Field	Contract
`date`required	string Local calendar date, YYYY-MM-DD.
`periods`optional	array<DatePeriod> Intervals replacing the whole date. Empty means closed, including previous-day spillover. max items: 8

Translation

Field	Contract
`name`required	string Localized name. Render as text. min length: 1 · max length: 256
`description`optional	string Localized description. Empty when not provided. Render as text. max length: 4000 · default: ""

Variant

Field	Contract
`id`required	string Identifies the combination. Don't send it in orders; send the choices instead. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`selections`required	array<Selection> The variant choices that make up this combination. max items: 100
`price`required	integer Price in bani for this combination, replacing the product price. min: 0.0 · max: 100000000.0
`discount`optional	integer Published discount in bani per unit, subtracted from price before deposits, packaging and extras. Defaults to zero. Never send a discount in an order. min: 0.0 · max: 100000000.0 · default: 0
`deposit`optional	integer Deposit in bani for this combination, replacing the product deposit. min: 0.0 · max: 100000000.0 · default: 0
`available`optional	boolean False when this combination can't be ordered. default: true

WebhookConfiguration

Field	Contract
`url`required	string Public HTTPS callback URL on port 443. No query, fragment or credentials. max length: 2048
`enabled`optional	boolean Enable order, availability, menu and connection notifications. False cancels queued deliveries. default: true

WebhookDelivery

Field	Contract
`id`required	string Stable event ID. Deduplicate deliveries using this value.
`connection_id`required	string POS connection identified by this event.
`external_order_id`required	string \| null Your order ID, or null for all connection and menu events.
`state`required	string pending, delivered, failed or cancelled. Only failed events can be manually retried. values: ["pending", "delivered", "failed", "cancelled"]
`attempts`required	integer Number of claimed delivery attempts in the current retry window.
`last_status`required	integer \| null Last receiver HTTP status, or null when no response was received.
`failure`required	string \| null Safe failure code, or null. Receiver response bodies are never exposed.

WebhookSubscription

Field	Contract
`url`optional	string \| null Registered callback URL, or null before configuration.
`enabled`optional	boolean Whether webhook watching and delivery are enabled. default: false
`signing_secret`optional	string \| null Returned only when creating, changing the URL or rotating the secret. Store it securely in your backend.

AvailabilityEventData

Field	Contract
`accepting_orders`required	boolean Whether checkout is available now; scheduled slots must be evaluated through GET menu.
`reason`required	string accepting, paused, closed or menu_not_published. values: ["accepting", "paused", "closed", "menu_not_published"]
`pause_until`optional	string \| null UTC pause expiry, or null for no timed pause. Expiry still respects opening hours. default: null

ConnectionEventData

Field	Contract
`enabled`required	boolean Whether this POS connection is enabled. Refresh the connection list; disabled connections cannot receive orders.
`location_id`required	string The restaurant location's ID.
`location_name`required	string Location name to show customers.
`pos_id`required	string The receiving register's ID.
`pos_name`required	string Register name, useful for support.

DeliveryEventData

Field	Contract
`external_order_id`required	string Your order ID. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`request_id`required	string Your stable report request ID. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`status`required	string Delivery state submitted in this report, not necessarily the latest state. values: ["assigned", "arrived", "picked_up", "delivered"]
`estimated_pickup_at`optional	string \| null Pickup estimate supplied in this report, or null. default: null
`estimated_delivery_at`optional	string \| null Delivery estimate supplied in this report, or null. default: null

MenuEventData

Field	Contract
`revision`required	string Published revision at observation time. Refresh the connection menu; availability can change without a new revision.

RefundEventData

Field	Contract
`external_order_id`required	string Your order ID. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`request_id`required	string Your stable report request ID. min length: 1 · max length: 100 · pattern: "^[A-Za-z0-9_-]+$"
`outcome`required	string Final outcome reported by your website: succeeded or failed. Not verified with a processor. values: ["succeeded", "failed"]
`amount`required	integer Refund amount for this report, in bani. min: 0 · max: 100000000

SettingsEventData

Field	Contract
`settings_version`required	string Opaque fingerprint of observed operating settings. Refresh the connection menu for current opening_hours and scheduling; this is not a menu revision. pattern: "^[a-f0-9]{64}$"

WebhookEvent

Field	Contract
`id`required	string Stable event ID. Deduplicate deliveries using this value. pattern: "^evt_[a-f0-9]{48}$"
`type`required	string Order updates, delivery/refund reports, restaurant availability, menus or POS connection changes. values: ["order.status_changed", "order.updated", "order.delivery_updated", "refund.reported", "connection.availability_changed", "menu.published", "menu.availability_changed", "connection.changed", "connection.settings_changed"]
`sequence`required	integer Increasing per-order sequence; non-order events use a separate sequence for each connection and event type. Ignore older updates. min: 1
`observed_at`required	string UTC observation time, not the time of the restaurant action.
`connection_id`required	string POS connection identified by this event.
`data`required	OrderReceipt \| RefundEventData \| DeliveryEventData \| AvailabilityEventData \| MenuEventData \| ConnectionEventData \| SettingsEventData Payload depends on type: OrderReceipt, DeliveryEventData, RefundEventData, AvailabilityEventData, MenuEventData, ConnectionEventData or SettingsEventData.