> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Odoo

> A production pattern for syncing Odoo contacts and POS orders with Perkstar.

Build the connector as an Odoo server module or trusted middleware service. Do
not call Perkstar directly from browser-side Odoo code because that would expose
the API key.

## Recommended mapping

| Odoo | Perkstar | Rule |
| - | - | - |
| Company + `res.partner.id` | `customer.external_ref` | `odoo:<company_id>:partner:<id>` |
| POS order ID | `external_transaction_id` | `odoo:<company_id>:pos_order:<id>` |
| POS location | `metadata.locationId` | Store the Perkstar location UUID on the Odoo shop config |
| Loyalty programme | `card_id` | Explicit mapping; do not infer when several cards exist |
| Refund ID | reversal idempotency key | One stable key per refund operation |

## Contact sync

When an Odoo contact becomes eligible for loyalty, call `POST /customers` with
`external_ref`. That endpoint upserts on the external reference: a retry returns
the existing customer without overwriting it.

```json theme={null}
{
  "external_ref": "odoo:4:partner:981",
  "email": "customer@example.com",
  "first_name": "Amina",
  "last_name": "Khan"
}
```

Keep Odoo as the source of truth only for fields the business has deliberately
chosen to sync. Do not overwrite consent flags from a generic contact import.

## Order completion

On a paid or completed POS order, call `/marketplace/accrue`. Send:

* the mapped `card_id`;
* the Odoo partner external reference;
* the stable POS order reference;
* `amount_pence` when the card earns from spend; and
* the mapped Perkstar `locationId`.

Use Odoo's post-commit or job queue mechanism. If an Odoo transaction later
rolls back, it must not leave a loyalty award behind.

## Refunds and cancellations

On a confirmed refund, call `/marketplace/reverse` with the original external
transaction reference. Record the returned Perkstar reversal ID on the refund
record so support can trace both sides.

## Reconciliation job

Run a scheduled reconciliation that:

1. finds completed Odoo orders missing a Perkstar transaction ID;
2. retries them with the original idempotency and transaction references;
3. compares recent Perkstar transactions with Odoo orders; and
4. alerts on unmatched or terminal failures.

Webhooks make the integration responsive; reconciliation makes it reliable.

## Go-live sequence

1. Develop with a test key and existing Perkstar enrolment.
2. Verify test webhooks and duplicate delivery handling.
3. Test a timeout followed by a retry.
4. Test a full and partial Odoo refund policy with the business.
5. Create a new narrowly scoped live key.
6. Process one low-risk live order and confirm the wallet update.
7. Enable the connector location by location.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.