# Yatoon Booking Developer Guide

## Embedding

Use the native Yatoon blocks in Gutenberg, the **Yatoon Booking** Elementor widget, or these shortcodes:

| Experience | Shortcode |
| --- | --- |
| Booking form | `[yatoon_booking]` |
| Service menu | `[yatoon_service_menu]` |
| Staff portal | `[yatoon_staff_portal]` |
| Customer portal | `[yatoon_customer_portal]` |
| Customer booking management | `[yatoon_manage_booking]` |
| Catalog | `[yatoon_catalog]` |
| Gallery | `[yatoon_gallery]` |
| Reviews | `[yatoon_reviews]` |

## Lifecycle Hooks

`yatoon_booking_created` receives one booking data array after the booking is stored.

```php
add_action( 'yatoon_booking_created', function( $booking ) {
    $booking_id = absint( $booking['booking_id'] ?? 0 );
}, 10, 1 );
```

`yatoon_booking_status_changed` receives booking ID, new status, and old status.

`yatoon_payment_status_changed` receives booking ID, new status, old status, and an optional note.

`yatoon_run_job_{job_type}` receives a decoded payload for custom durable queue jobs.

```php
YATOON_Job_Queue::enqueue(
    'sync_crm',
    array( 'booking_id' => 123 ),
    30
);

add_action( 'yatoon_run_job_sync_crm', function( $payload ) {
    // Throw an exception to use the queue retry policy.
} );
```

## Automation Webhooks

Create webhook automations under **Yatoon Booking > Operations > Automation**. Payloads contain:

```json
{
  "event": "booking_created",
  "condition": "",
  "booking": {
    "id": 123,
    "customer_name": "Customer",
    "service_name": "Service",
    "staff_name": "Team member",
    "start_time": "2026-07-01 10:00:00",
    "total_price": "50.00"
  }
}
```

Return an HTTP status below 400. Failed deliveries are retried automatically.

## Data Model

Core booking records use `{prefix}yatoon_bookings`. Formal 4.0 adds:

- `{prefix}yatoon_jobs`: durable background jobs and retry state.
- `{prefix}yatoon_performance`: request duration and memory samples.
- `{prefix}yatoon_orders`: order totals, paid amount, refunds, and balance.
- `{prefix}yatoon_order_items`: booking services and tips.
- `{prefix}yatoon_invoices`: invoice numbers and private public-view tokens.
- `{prefix}yatoon_payments`: append-only payment and refund records.
- `{prefix}yatoon_resources`: shared equipment or room capacity.
- `{prefix}yatoon_resource_services`: service resource requirements.

Use WordPress APIs and lifecycle hooks instead of writing directly to these tables.

## Operations

Run the built-in health test with WP-CLI:

```bash
wp yatoon smoke-test
```

Review request timing and failed jobs under **Yatoon Booking > Performance**. Retry failed work from that screen after correcting the underlying mail, SMS, calendar, or webhook configuration.