# API Contract

Each Engage capability maps to one adapter method exposed by the partner integration. After these methods are implemented, Engage routes the relevant operation to them automatically.

The reference mappings below show how the Nector implementation satisfies the contract.

> See the Fynd Engage API Reference ↗ for the current API schemas.


## Required capabilities

### Engage to adapter mapping

| Capability | Engage endpoint | Adapter method |
|  --- | --- | --- |
| Search or get customer | `GET /v2/users/:userId` | `getUser` |
| Register customer | `POST /v2/users` | `registerUser` |
| Update customer | `PATCH /v2/users/:userId` | `updateUser` |
| Wallet balance | `GET /v2/wallet/:userId` | `getWalletDetails` |
| Redeemable or earn preview | `POST /v2/order/loyalty/calculate` | `calculateLoyaltyPoints` |
| Discount preview | `POST /v2/order/discount` | `calculateDiscount` |
| Apply points and hold on cart | `POST /v2/order` | `createOrder` |
| Revert hold | `POST /v2/order/transaction/cancel` | `cancelOrder` |
| Credit earned points | Webhook driven | `addPoints` |
| Health check | Not applicable | `testConnection` |


### Nector reference mappings

| Capability | Reference mapping |
|  --- | --- |
| Search or get customer | `POST /search-customer` by mobile number |
| Register customer | Created from the `user_create` webhook |
| Update customer | `POST /search-customer` |
| Wallet balance | `search-customer` response field `wallet.available` |
| Redeemable, earn, or discount preview | `POST /redemption` with `action:list` |
| Apply points and hold on cart | `redemption` with `action:perform` and reference `<salesChannelId>:<cartId>` |
| Revert hold | `redemption` with `action:revert` |
| Credit earned points | `POST /issue-credits` |
| Health check | `search-customer` probe |


Contract notes
Customer identity is passed as a **mobile number**. The redemption reference ID is always `<salesChannelId>:<cartId>`. Use the same key to perform, revert, or confirm the hold so the operation remains idempotent. The wallet type in the Nector reference implementation is `coins`

## Adapter behavior

### Customer operations

- Resolve customers by mobile number.
- Map the provider record into the Engage User schema.
- Create customers from `user_create` events.
- Synchronize profile changes from `user_update` events.


### Wallet and preview operations

- Return the available wallet balance in real time.
- Calculate available loyalty points and discounts without creating an order.
- Return values in the Engage response schema.


### Redemption operations

- Create a reversible hold using `<salesChannelId>:<cartId>`.
- Revert a hold using the same reference.
- Confirm the hold after the matching order-placed event.
- Credit earned points only after a qualifying shipment reaches a terminal delivery status.


### Connection test

Expose a lightweight test that Engage can use to validate credentials and provider availability before live traffic is enabled.

Keep the reference stable
Do not replace the cart-based reference with an order ID. The order does not exist when points are applied during checkout