Developer Studio

ZintGO POS API Documentation

Build POS integrations for customer lookup, point earning, reward redemption, and store loyalty configuration.

Additional resources:
Integration profile

POS Partner API

1.0.0
AuthBearer token
FormatJSON
Success200
ScopeStore based
Home ZintGO API Get Auth Token

Get Auth Token

POST/auth/getAuthToken1.0.0

Issue a store-scoped bearer token for POS integration requests.

Additional resources:

storeId

REQUIREDstringbody

Max Length: 80

Example: STORE_ID

Unique identifier issued for the store.

clientSecret

REQUIREDstringbody

Max Length: 160

Example: CLIENT_SECRET

Secret issued to the POS partner. Keep this value private.

{
  "storeId": "STORE_ID",
  "clientSecret": "CLIENT_SECRET"
}
{
  "access_token": "YOUR_POS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}
200Success
401The request was unauthorized
403The request resource is forbidden for user
501The request cannot be validated
500Internal server error

Add Customer

POST/customers/add1.0.0

Create or match a customer and attach a wallet for the authenticated store.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

Idempotency-Key

REQUIREDstringheader

Max Length: 120

Example: IDEMPOTENCY_KEY

Unique key to prevent duplicate POST writes.

Correlation-ID

REQUIREDstringheader

Max Length: 120

Example: CORRELATION_ID

Trace id generated by the POS.

customerEmail

OPTIONALstringbody

Max Length: 160

Example: CUSTOMER_EMAIL

Customer email. Use either email or phone.

customerPhone

OPTIONALstringbody

Max Length: 32

Example: CUSTOMER_PHONE

Customer mobile number. Use either phone or email.

displayName

OPTIONALstringbody

Max Length: 120

Example: Sample Customer

Customer-facing display name.

{
  "customerEmail": "CUSTOMER_EMAIL",
  "customerPhone": "CUSTOMER_PHONE",
  "displayName": "Sample Customer"
}
{
  "storeId": "STORE_ID",
  "customerUid": "CUSTOMER_UID",
  "customerEmail": "CUSTOMER_EMAIL",
  "customerPhone": "CUSTOMER_PHONE",
  "created": true,
  "matchedBy": "phone",
  "customer": {
    "uid": "CUSTOMER_UID",
    "exists": true,
    "displayName": "Sample Customer",
    "email": "CUSTOMER_EMAIL",
    "phone": "CUSTOMER_PHONE"
  },
  "wallet": {
    "exists": true,
    "points": 42
  }
}
200Success
420Duplicate idempotency key
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
501The request cannot be validated
500Internal server error

Read Customer

GET/customers/read1.0.0

Read customer and wallet details for the authenticated store when a wallet exists.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

customerUid

OPTIONALstringquery

Max Length: 80

Example: CUSTOMER_UID

Use any one customer identifier.

customerEmail

OPTIONALstringquery

Max Length: 160

Example: CUSTOMER_EMAIL

Use any one customer identifier.

customerPhone

OPTIONALstringquery

Max Length: 32

Example: CUSTOMER_PHONE

Use any one customer identifier.

GET /customers/read?customerPhone=CUSTOMER_PHONE
Authorization: Bearer YOUR_POS_TOKEN
{
  "storeId": "STORE_ID",
  "customerUid": "CUSTOMER_UID",
  "customerEmail": "CUSTOMER_EMAIL",
  "customerPhone": "CUSTOMER_PHONE",
  "customer": {
    "uid": "CUSTOMER_UID",
    "exists": true,
    "displayName": "Sample Customer"
  },
  "wallet": {
    "exists": true,
    "points": 42
  }
}
200Success
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
501The request cannot be validated
500Internal server error

Read Store Config

GET/store/config1.0.0

Read current earn and reward configuration for the authenticated store.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

GET /store/config
Authorization: Bearer YOUR_POS_TOKEN
{
  "storeId": "STORE_ID",
  "config": {
    "qrType": "dynamic",
    "earnMode": "bill",
    "pointsPerVisit": 1,
    "pointsPerQty": 1,
    "pointsPer10": 1,
    "rewardType": "percent",
    "rewardThresholdPoints": 100,
    "rewardLabel": "10% off next bill",
    "rewardConfig": {
      "percentOff": 10,
      "percentTarget": "bill",
      "percentItem": ""
    }
  }
}
200Success
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
500Internal server error

Update Store Config

POST/store/config1.0.0

Update the store reward rule, earn mode, threshold, and customer-facing reward label.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

Idempotency-Key

REQUIREDstringheader

Max Length: 120

Example: IDEMPOTENCY_KEY

Unique key to prevent duplicate config updates.

Correlation-ID

REQUIREDstringheader

Max Length: 120

Example: CORRELATION_ID

Trace id generated by the POS.

earnMode

OPTIONALstringbody

Allowed: visit, quantity, bill

Example: bill

Controls how points are calculated.

rewardType

OPTIONALstringbody

Allowed: free, percent, amount

Example: percent

Controls the redemption style.

rewardThresholdPoints

OPTIONALnumberbody

Minimum: 1

Example: 100

Points required before a reward becomes available.

{
  "qrType": "dynamic",
  "earnMode": "bill",
  "pointsPer10": 1,
  "rewardType": "percent",
  "rewardThresholdPoints": 100,
  "rewardConfig": {
    "percentOff": 10,
    "percentTarget": "bill",
    "percentItem": ""
  }
}
{
  "storeId": "STORE_ID",
  "config": {
    "earnMode": "bill",
    "rewardType": "percent",
    "rewardThresholdPoints": 100,
    "rewardLabel": "10% off next bill"
  }
}
200Success
420Duplicate idempotency key
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
501The request cannot be validated
500Internal server error

Add Points

POST/points/add1.0.0

Add an explicit number of loyalty points to a customer wallet.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

Idempotency-Key

REQUIREDstringheader

Max Length: 120

Example: IDEMPOTENCY_KEY

Unique key to prevent duplicate point additions.

Correlation-ID

REQUIREDstringheader

Max Length: 120

Example: CORRELATION_ID

Trace id generated by the POS.

customerUid

OPTIONALstringbody

Max Length: 80

Example: CUSTOMER_UID

Use any one customer identifier.

customerEmail

OPTIONALstringbody

Max Length: 160

Example: CUSTOMER_EMAIL

Use any one customer identifier.

customerPhone

OPTIONALstringbody

Max Length: 32

Example: CUSTOMER_PHONE

Use any one customer identifier.

points

REQUIREDnumberbody

Minimum: 1

Example: 5

Number of points to add.

{
  "customerUid": "CUSTOMER_UID",
  "points": 5,
  "note": "POS sale"
}
{
  "storeId": "STORE_ID",
  "customerUid": "CUSTOMER_UID",
  "customerEmail": "CUSTOMER_EMAIL",
  "customerPhone": "CUSTOMER_PHONE",
  "pointsAdded": 5,
  "newPoints": 47
}
200Success
420Duplicate idempotency key
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
501The request cannot be validated
500Internal server error

Add Extended Points

POST/points/addExtended1.0.0

Calculate points using the store configuration and return reward availability after the add.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

Idempotency-Key

REQUIREDstringheader

Max Length: 120

Example: IDEMPOTENCY_KEY

Unique key to prevent duplicate point additions.

Correlation-ID

REQUIREDstringheader

Max Length: 120

Example: CORRELATION_ID

Trace id generated by the POS.

customerPhone

OPTIONALstringbody

Max Length: 32

Example: CUSTOMER_PHONE

Use any one customer identifier.

value

OPTIONALnumberbody

Example: 48.50

Example: 48.50

Generic value used by configured earn mode.

quantity

OPTIONALnumberbody

Example: 2

Example: 2

Quantity value for quantity based programs.

billAmount

OPTIONALnumberbody

Example: 48.50

Example: 48.50

Bill value for bill based programs.

{
  "customerPhone": "CUSTOMER_PHONE",
  "value": 48.5
}
{
  "storeId": "STORE_ID",
  "customerUid": "CUSTOMER_UID",
  "customerEmail": "CUSTOMER_EMAIL",
  "customerPhone": "CUSTOMER_PHONE",
  "pointsAdded": 4,
  "newPoints": 51,
  "rewardEligible": false,
  "reward": {
    "rewardThresholdPoints": 100,
    "rewardType": "percent",
    "rewardLabel": "10% off next bill",
    "rewardConfig": {
      "percentOff": 10,
      "percentTarget": "bill",
      "percentItem": ""
    },
    "availableRewards": 0
  }
}
200Success
420Duplicate idempotency key
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
501The request cannot be validated
500Internal server error

Read Points

GET/points/read1.0.0

Read the current point balance and wallet status for a customer.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

customerUid

OPTIONALstringquery

Max Length: 80

Example: CUSTOMER_UID

Use any one customer identifier.

customerEmail

OPTIONALstringquery

Max Length: 160

Example: CUSTOMER_EMAIL

Use any one customer identifier.

customerPhone

OPTIONALstringquery

Max Length: 32

Example: CUSTOMER_PHONE

Use any one customer identifier.

GET /points/read?customerEmail=CUSTOMER_EMAIL
Authorization: Bearer YOUR_POS_TOKEN
{
  "storeId": "STORE_ID",
  "customerUid": "CUSTOMER_UID",
  "customerEmail": "CUSTOMER_EMAIL",
  "customerPhone": "CUSTOMER_PHONE",
  "points": 51,
  "walletExists": true
}
200Success
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
501The request cannot be validated
500Internal server error

Read Extended Points

GET/points/readExtended1.0.0

Read point balance, wallet status, and reward summary for a customer.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

customerUid

OPTIONALstringquery

Max Length: 80

Example: CUSTOMER_UID

Use any one customer identifier.

customerEmail

OPTIONALstringquery

Max Length: 160

Example: CUSTOMER_EMAIL

Use any one customer identifier.

customerPhone

OPTIONALstringquery

Max Length: 32

Example: CUSTOMER_PHONE

Use any one customer identifier.

GET /points/readExtended?customerUid=CUSTOMER_UID
Authorization: Bearer YOUR_POS_TOKEN
{
  "storeId": "STORE_ID",
  "customerUid": "CUSTOMER_UID",
  "customerEmail": "CUSTOMER_EMAIL",
  "customerPhone": "CUSTOMER_PHONE",
  "points": 51,
  "walletExists": true,
  "reward": {
    "rewardThresholdPoints": 100,
    "rewardType": "percent",
    "rewardLabel": "10% off next bill",
    "rewardConfig": {
      "percentOff": 10,
      "percentTarget": "bill",
      "percentItem": ""
    },
    "availableRewards": 0
  }
}
200Success
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
501The request cannot be validated
500Internal server error

Redeem Reward

POST/points/redeem1.0.0

Redeem one configured reward and return the calculated discount summary.

Authorization

REQUIREDstringheader

Max Length: 1200

Example: Bearer YOUR_POS_TOKEN

Store-scoped bearer token.

Idempotency-Key

REQUIREDstringheader

Max Length: 120

Example: IDEMPOTENCY_KEY

Unique key to prevent duplicate redemptions.

Correlation-ID

REQUIREDstringheader

Max Length: 120

Example: CORRELATION_ID

Trace id generated by the POS.

customerUid

OPTIONALstringbody

Max Length: 80

Example: CUSTOMER_UID

Use any one customer identifier.

billAmount

OPTIONALnumberbody

Example: 25.00

Example: 25.00

Bill amount used for bill discount calculation.

{
  "customerUid": "CUSTOMER_UID",
  "billAmount": 25.0
}
{
  "storeId": "STORE_ID",
  "customerUid": "CUSTOMER_UID",
  "customerEmail": "CUSTOMER_EMAIL",
  "customerPhone": "CUSTOMER_PHONE",
  "txId": "TRANSACTION_ID",
  "pointsRedeemed": 100,
  "newPoints": 25,
  "rewardLabel": "10% off next bill",
  "billAmount": 25,
  "discountAmount": 2.5,
  "finalBillAmount": 22.5,
  "reward": {
    "rewardThresholdPoints": 100,
    "rewardType": "percent",
    "rewardLabel": "10% off next bill",
    "rewardConfig": {
      "percentOff": 10,
      "percentTarget": "bill",
      "percentItem": ""
    },
    "billAmount": 25,
    "discountAmount": 2.5,
    "finalBillAmount": 22.5,
    "availableRewards": 0
  }
}
200Success
420Duplicate idempotency key
401The request was unauthorized
403The request resource is forbidden for user
404The request resource does not exist
412Reward cannot be redeemed
501The request cannot be validated
500Internal server error