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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Replay-safe request key. Repeated requests with the same value within 24h return the original response unchanged.
Maximum string length:
255Body
application/json
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
Show child attributes
Show child attributes
Show child attributes
Optional. Defaults to the org's single ACTIVE card. If
multiple ACTIVE cards exist, this is required (else 400
ambiguous_default_card).
Fields used when create_customer_if_missing is true and no existing customer matches the identifier.
Show child attributes
Show child attributes
Response
Existing transaction returned (external_transaction_id dedup hit).
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Set to true when the response is a replay of an existing transaction (external_transaction_id dedup hit). Absent on fresh creates.
Was this page helpful?
⌘I
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>"
}
}