# Salla OAuth Scopes Required for HalaVoice AI

## Required Scopes

| Scope | Purpose | Why Needed |
|-------|---------|------------|
| `offline_access` | Long-lived refresh token | Background jobs run when merchant is offline (webhooks, calls, WhatsApp) |
| `merchant.basic_info` | Read merchant/store details | Display store name, owner info in dashboard; required for OAuth flow |
| `merchant.contact_info` | Read merchant contact info | Access store phone, email for notifications |
| `merchant.subscription` | Read/write subscription | Manage app subscription plans, trials, billing |
| `sales.order.read` | Read orders | Detect COD orders for confirmation calls |
| `sales.order.write` | Update/cancel orders | Auto-cancel COD orders when customer declines; update order status |
| `sales.order.read_custom_fields` | Read order custom fields | Access additional order metadata |
| `sales.abandoned_cart.read` | Read abandoned carts | Detect and recover abandoned carts |
| `sales.customer.read` | Read customer data | Get customer name, phone for calls/messages |
| `sales.customer.write` | Update customer data | Tag customers, store interaction history |
| `sales.shipment.read` | Read shipment data | Detect shipping events for WhatsApp notifications |
| `sales.shipment.write` | Update shipment data | Not applicable currently; reserved for future |
| `setting.webhook.read` | Read webhook configuration | Verify webhook subscriptions |
| `setting.webhook.write` | Register webhook endpoints | Auto-register required webhooks on install |

## Total Scopes String
```
offline_access merchant.basic_info merchant.contact_info merchant.subscription sales.order.read sales.order.write sales.order.read_custom_fields sales.abandoned_cart.read sales.customer.read sales.customer.write sales.shipment.read sales.shipment.write setting.webhook.read setting.webhook.write
```

## Webhook Events to Subscribe

### App Events (Required)
- `app.store.authorize` — Token delivery (Easy Mode)
- `app.installed` — Installation confirmation
- `app.uninstalled` — Cleanup
- `app.subscription.started` — Subscription activated
- `app.subscription.expired` — Expiration handling
- `app.subscription.canceled` — Cancellation handling
- `app.subscription.renewed` — Renewal notification
- `app.trial.started` — Trial start
- `app.settings.updated` — Settings changes

### Store Events (Required)
- `order.created` — New order (COD confirmation trigger)
- `order.status.updated` — Status change (shipping/delivery triggers)
- `order.cancelled` — Order cancelled
- `order.updated` — Order modified
- `order.payment.updated` — Payment status change
- `abandoned.cart` — Cart abandonment (recovery trigger)
- `customer.created` — New customer
- `customer.updated` — Customer profile update
- `shipment.created` — Shipment created (WhatsApp trigger)
- `shipment.updated` — Shipment status update

### Store Events (Optional — Future Use)
- `review.added` — Product review
- `product.created` / `product.updated` — Inventory sync

## Scope Request Justification (for Salla Review)

> "HalaVoice AI requires `sales.order.write` to automatically cancel COD orders when customers decline during confirmation calls — without manual merchant intervention. Similarly, read scopes are needed to detect events (new orders, abandoned carts, shipments) and trigger appropriate AI voice/WhatsApp actions. `offline_access` ensures background jobs can run when the merchant is not actively using the app."