Skip to main content
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.

​
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.
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 platformIdempotency and retriesBuild a POS integrationChangelogAuthentication and scopes