Marketplace

Find-or-create customer + post transaction in one call

Resolves the customer in this fixed priority order:

customer_id → tenant-scoped Perkstar customer
card_serial → POS barcode or legacy pass serial → customer
external_ref → (orgId, externalRef) lookup
email (case-insensitive)
phone (normalised E.164 with a legacy raw-value fallback)

First match wins. On miss, creates a customer when create_customer_if_missing is true (the default). A missing customer_id alone returns 404 instead of creating a replacement.

The transaction.external_transaction_id field is enforced as permanently unique per (orgId, externalTransactionId). An exact retry with the same canonical target, type, amount, and request fields returns the existing transaction at HTTP 200 instead of double-crediting, no matter how long has passed. Reusing the id for a different request returns 409 external_transaction_id_conflict. Use this for POS-side stable ids (Toast order #s, Shopify checkout ids, Square payment ids). Test and live transactions cannot share the same value; a cross-environment replay is rejected with 422. Provider-owned prefixes such as sq_payment_ are reserved for managed integrations; use a namespace owned by your app.

Idempotency-Key (24h replay cache) and external_transaction_id (permanent dedupe) coexist — use both for full robustness.

With a test credential this endpoint never creates a customer or enrolment. Resolve an existing record and card first, then post the isolated transaction. A missing customer or enrolment returns 404.

POST

https://dashboard.perkstar.co.uk/api/v1

marketplace

accrue

Find-or-create customer + post transaction in one call

curl --request POST \
  --url https://dashboard.perkstar.co.uk/api/v1/marketplace/accrue \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "identifier": {
    "customer_id": "<string>",
    "phone": "<string>",
    "email": "jsmith@example.com",
    "external_ref": "<string>",
    "card_serial": "<string>"
  },
  "transaction": {
    "amount_pence": 1,
    "delta": 123,
    "external_transaction_id": "<string>",
    "note": "<string>",
    "metadata": {}
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    identifier: {
      customer_id: '<string>',
      phone: '<string>',
      email: 'jsmith@example.com',
      external_ref: '<string>',
      card_serial: '<string>'
    },
    transaction: {
      amount_pence: 1,
      delta: 123,
      external_transaction_id: '<string>',
      note: '<string>',
      metadata: {}
    }
  })
};

fetch('https://dashboard.perkstar.co.uk/api/v1/marketplace/accrue', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://dashboard.perkstar.co.uk/api/v1/marketplace/accrue"

payload = {
    "identifier": {
        "customer_id": "<string>",
        "phone": "<string>",
        "email": "jsmith@example.com",
        "external_ref": "<string>",
        "card_serial": "<string>"
    },
    "transaction": {
        "amount_pence": 1,
        "delta": 123,
        "external_transaction_id": "<string>",
        "note": "<string>",
        "metadata": {}
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dashboard.perkstar.co.uk/api/v1/marketplace/accrue",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'identifier' => [
        'customer_id' => '<string>',
        'phone' => '<string>',
        'email' => 'jsmith@example.com',
        'external_ref' => '<string>',
        'card_serial' => '<string>'
    ],
    'transaction' => [
        'amount_pence' => 1,
        'delta' => 123,
        'external_transaction_id' => '<string>',
        'note' => '<string>',
        'metadata' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "customer": {
    "id": "<string>",
    "customer_number": 123,
    "email": "<string>",
    "phone": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "date_of_birth": "2023-11-07T05:31:56Z",
    "consent_marketing": true,
    "consent_ad_tracking": true,
    "external_ref": "<string>",
    "anonymized_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "enrollment": {
    "id": "<string>",
    "customer_id": "<string>",
    "card_id": "<string>",
    "status": "ACTIVE",
    "balance": 123,
    "redemptions_count": 123,
    "cumulative_spend_pence": 123,
    "bonus_points_balance": 123,
    "enrolled_at": "2023-11-07T05:31:56Z",
    "last_activity_at": "2023-11-07T05:31:56Z",
    "wallet_passes": {
      "apple": "<string>",
      "google": "<string>"
    }
  },
  "transaction": {
    "id": "<string>",
    "enrollment_id": "<string>",
    "type": "STAMP",
    "source": "SCANNER",
    "delta": 123,
    "amount_pence": 123,
    "note": "<string>",
    "external_id": "<string>",
    "external_transaction_id": "<string>",
    "reverses_transaction_id": "<string>",
    "reason_text": "<string>",
    "test_mode": true,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "wallet_passes": {
    "apple": "<string>",
    "google": "<string>"
  },
  "customer_created": true,
  "enrollment_created": true,
  "idempotent_replay": true
}

{
  "customer": {
    "id": "<string>",
    "customer_number": 123,
    "email": "<string>",
    "phone": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "date_of_birth": "2023-11-07T05:31:56Z",
    "consent_marketing": true,
    "consent_ad_tracking": true,
    "external_ref": "<string>",
    "anonymized_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "enrollment": {
    "id": "<string>",
    "customer_id": "<string>",
    "card_id": "<string>",
    "status": "ACTIVE",
    "balance": 123,
    "redemptions_count": 123,
    "cumulative_spend_pence": 123,
    "bonus_points_balance": 123,
    "enrolled_at": "2023-11-07T05:31:56Z",
    "last_activity_at": "2023-11-07T05:31:56Z",
    "wallet_passes": {
      "apple": "<string>",
      "google": "<string>"
    }
  },
  "transaction": {
    "id": "<string>",
    "enrollment_id": "<string>",
    "type": "STAMP",
    "source": "SCANNER",
    "delta": 123,
    "amount_pence": 123,
    "note": "<string>",
    "external_id": "<string>",
    "external_transaction_id": "<string>",
    "reverses_transaction_id": "<string>",
    "reason_text": "<string>",
    "test_mode": true,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "wallet_passes": {
    "apple": "<string>",
    "google": "<string>"
  },
  "customer_created": true,
  "enrollment_created": true,
  "idempotent_replay": true
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Replay-safe request key. Repeated requests with the same value within 24h return the original response unchanged.

Maximum string length: 255

Body

application/json

identifier

object

required

Customer identifier block. At least ONE field must be present. Resolution order is fixed: customer_id → card_serial → external_ref → email → phone. First match wins.

Show child attributes

transaction

object

required

Show child attributes

card_id

string

Optional. Defaults to the org's single ACTIVE card. If multiple ACTIVE cards exist, this is required (else 400 ambiguous_default_card).

create_customer_if_missing

boolean

default:true

customer_fields

object

Fields used when create_customer_if_missing is true and no existing customer matches the identifier.

Show child attributes

Response

Existing transaction returned (external_transaction_id dedup hit).

customer

object

Show child attributes

enrollment

object

Show child attributes

transaction

object

Show child attributes

wallet_passes

object | null

Show child attributes

customer_created

boolean

enrollment_created

boolean

idempotent_replay

boolean

Set to true when the response is a replay of an existing transaction (external_transaction_id dedup hit). Absent on fresh creates.

Find-or-create customer + post transaction in one call

curl --request POST \
  --url https://dashboard.perkstar.co.uk/api/v1/marketplace/accrue \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "identifier": {
    "customer_id": "<string>",
    "phone": "<string>",
    "email": "jsmith@example.com",
    "external_ref": "<string>",
    "card_serial": "<string>"
  },
  "transaction": {
    "amount_pence": 1,
    "delta": 123,
    "external_transaction_id": "<string>",
    "note": "<string>",
    "metadata": {}
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    identifier: {
      customer_id: '<string>',
      phone: '<string>',
      email: 'jsmith@example.com',
      external_ref: '<string>',
      card_serial: '<string>'
    },
    transaction: {
      amount_pence: 1,
      delta: 123,
      external_transaction_id: '<string>',
      note: '<string>',
      metadata: {}
    }
  })
};

fetch('https://dashboard.perkstar.co.uk/api/v1/marketplace/accrue', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://dashboard.perkstar.co.uk/api/v1/marketplace/accrue"

payload = {
    "identifier": {
        "customer_id": "<string>",
        "phone": "<string>",
        "email": "jsmith@example.com",
        "external_ref": "<string>",
        "card_serial": "<string>"
    },
    "transaction": {
        "amount_pence": 1,
        "delta": 123,
        "external_transaction_id": "<string>",
        "note": "<string>",
        "metadata": {}
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dashboard.perkstar.co.uk/api/v1/marketplace/accrue",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'identifier' => [
        'customer_id' => '<string>',
        'phone' => '<string>',
        'email' => 'jsmith@example.com',
        'external_ref' => '<string>',
        'card_serial' => '<string>'
    ],
    'transaction' => [
        'amount_pence' => 1,
        'delta' => 123,
        'external_transaction_id' => '<string>',
        'note' => '<string>',
        'metadata' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "customer": {
    "id": "<string>",
    "customer_number": 123,
    "email": "<string>",
    "phone": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "date_of_birth": "2023-11-07T05:31:56Z",
    "consent_marketing": true,
    "consent_ad_tracking": true,
    "external_ref": "<string>",
    "anonymized_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "enrollment": {
    "id": "<string>",
    "customer_id": "<string>",
    "card_id": "<string>",
    "status": "ACTIVE",
    "balance": 123,
    "redemptions_count": 123,
    "cumulative_spend_pence": 123,
    "bonus_points_balance": 123,
    "enrolled_at": "2023-11-07T05:31:56Z",
    "last_activity_at": "2023-11-07T05:31:56Z",
    "wallet_passes": {
      "apple": "<string>",
      "google": "<string>"
    }
  },
  "transaction": {
    "id": "<string>",
    "enrollment_id": "<string>",
    "type": "STAMP",
    "source": "SCANNER",
    "delta": 123,
    "amount_pence": 123,
    "note": "<string>",
    "external_id": "<string>",
    "external_transaction_id": "<string>",
    "reverses_transaction_id": "<string>",
    "reason_text": "<string>",
    "test_mode": true,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "wallet_passes": {
    "apple": "<string>",
    "google": "<string>"
  },
  "customer_created": true,
  "enrollment_created": true,
  "idempotent_replay": true
}

{
  "customer": {
    "id": "<string>",
    "customer_number": 123,
    "email": "<string>",
    "phone": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "date_of_birth": "2023-11-07T05:31:56Z",
    "consent_marketing": true,
    "consent_ad_tracking": true,
    "external_ref": "<string>",
    "anonymized_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "enrollment": {
    "id": "<string>",
    "customer_id": "<string>",
    "card_id": "<string>",
    "status": "ACTIVE",
    "balance": 123,
    "redemptions_count": 123,
    "cumulative_spend_pence": 123,
    "bonus_points_balance": 123,
    "enrolled_at": "2023-11-07T05:31:56Z",
    "last_activity_at": "2023-11-07T05:31:56Z",
    "wallet_passes": {
      "apple": "<string>",
      "google": "<string>"
    }
  },
  "transaction": {
    "id": "<string>",
    "enrollment_id": "<string>",
    "type": "STAMP",
    "source": "SCANNER",
    "delta": 123,
    "amount_pence": 123,
    "note": "<string>",
    "external_id": "<string>",
    "external_transaction_id": "<string>",
    "reverses_transaction_id": "<string>",
    "reason_text": "<string>",
    "test_mode": true,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "wallet_passes": {
    "apple": "<string>",
    "google": "<string>"
  },
  "customer_created": true,
  "enrollment_created": true,
  "idempotent_replay": true
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Customers

Enrollments

Transactions

Cards

Webhooks

Locations

Pushes

Marketplace

Outbound webhooks

Find-or-create customer + post transaction in one call

Authorizations

Headers

Body

Response