> ## 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.


## Related topics

- [Perkstar developer platform](/index.md)
- [Idempotency and retries](/fundamentals/idempotency.md)
- [Build a POS integration](/guides/pos.md)
- [Postman collection](/tools/postman.md)
- [Python SDK](/sdks/python.md)