Authentication & Global Headers

PRIMO APIs secure endpoints using Bearer Token Authentication. Every request must be submitted with Content-Type: application/json along with the standard header parameters listed below:

*Note: Merchant identity headers (company, brand, branch) are required for all transaction-related endpoints (Points, Coupons, and Privileges).

Standard Response Format

To ensure consistency across integrations, all endpoints adhere to a unified JSON response envelope schema:

Success Response Structure (HTTP 200)

{
  "successful": true,
  "errorCode": "00",
  "message": "Success",
  "httpStatus": 200,
  "data": {} 
}

Error Response Structure (HTTP 4xx / 5xx)

{
  "successful": false,
  "errorCode": "06",
  "message": "Validation error",
  "data": null
}

Core Global Error Codes

Create member no PII

The CRM provider would need to call this endpoint to create a member without personally identifiable information (PII).

HTTP Request

POST /v1.4/create-member/no-pii

Request Header

Content Body

Content will be in JSON object format which begins with { and ends with }.

Model: Accepted Consent

Sample Request

{ 
  "memberNo": "M0000000001", 
  "birthDate": "1990-01-01", 
  "acceptedTermId": 1, 
  "acceptedConsents": [ 
    { 
      "consentId": 2, 
      "action": "in" 
    }
  ], 
  "customData": { 
    "utm_source": "google", 
    "utm_medium": "cpc" 
  }, 
  "remark": "สมัครผ่าน LINE OA" 
}

HTTP Response

Successful Response

Model: Create Member Response

Model: Response Data

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "memberNo": "M0000000001" 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP27", 
  "message": "Member No already existed", 
  "data": null 
}

Status Codes

Error Codes

Get Profile

The CRM provider would need to call this endpoint to get member profile information.

HTTP Request

POST /v1.5/get-profile

Request Header

Content Body

Content will be in JSON object format which begins with { and ends with }.

Sample Request

{ 
  "identifierField": "member_no", 
  "identifierValue": "M0000000001" 
}

HTTP Response

Successful Response

Model: Get Profile Response

Model: Member

Model: Tier

Model: Point

Model: Latest Expired Date

Model: Address

Model: Opt

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "member": { 
      "memberNo": "M0000000001", 
      "firstNameTh": "วี", 
      "firstNameEn": "Vee", 
      "lastNameTh": "พรีโม", 
      "lastNameEn": "Primo", 
      "phone": "0987654321", 
      "email": "getprofile@example.com", 
      "memberStatus": "active", 
      "createdAt": "2026-03-16T17:39:38+07:00", 
      "updatedAt": "2026-03-16T17:39:38+07:00" 
    } 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP01", 
  "message": "Member not found", 
  "data": null 
}

Status Codes

Error Codes

Get Mark Profile

The CRM provider would need to call this endpoint to get masked member profile information.

HTTP Request

POST /v1.3/get-profile/mask

Request Header

Content Body

Content will be in JSON object format which begins with { and ends with }.

Sample Request

{ 
  "identifierField": "member_no", 
  "identifierValue": "M0000000001" 
}

HTTP Response

Successful Response

Model: Get Mark Profile Response

Model: Member

Model: Tier

Model: Point

Model: Latest Expired Date

Model: Address

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "member": { 
      "memberNo": "M0000000001", 
      "firstNameTh": "ว***", 
      "firstNameEn": "V****", 
      "lastNameTh": "พ****", 
      "lastNameEn": "P****", 
      "citizenId": "6***", 
      "passportNo": "P****", 
      "phone": "*****4321", 
      "email": "h****@****mobi" 
    } 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP01", 
  "message": "Member not found", 
  "data": null 
}

Status Codes

Error Codes

Get Point Balances

The CRM provider would need to call this endpoint to retrieve a member’s point balance information.

HTTP Request

POST /v1.3/points/get-balances

Request Header

Content Body

Content will be in JSON object format which begins with { and ends with }.

Sample Request

{ 
  "identifierField": "member_no", 
  "identifierValue": "M0000000001" 
}

HTTP Response

Successful Response

Model: Get Point Balances Response

Model: Points Data

Model: Latest Expired Date

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "points": [ 
      { 
        "pointCurrencyId": 1, 
        "pointBalance": 100, 
        "lastestExpiredDate": { 
          "expiredDate": "2020-12-31", 
          "point": 100 
        } 
      } 
    ] 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP01", 
  "message": "Member not found", 
  "data": null 
}

Status Codes

Error Codes

Earn Points

The CRM provider would need to call this endpoint to earn points for a member transaction.

HTTP Request

POST /v1.4/points/earn

Request Header

Content Body

Content will be in JSON object format which begins with { and ends with }.

Model: Order Item

Sample Request

{ 
  "identifierField": "member_no", 
  "identifierValue": "M0000000001", 
  "billNo": "812345678", 
  "channelRef": "yetimall", 
  "currency": "THB", 
  "earnableValue": 530, 
  "orderId": "OR0202303030001", 
  "orders": [ 
    { 
      "itemCode": "productRef", 
      "itemType": "product", 
      "sku": "00001", 
      "pricePerUnit": 100, 
      "itemQuantity": 5, 
      "itemDiscount": 0, 
      "orderAmount": 500, 
      "subtotal": 500, 
      "taxOrVat": 10, 
      "salesAfterTax": 510, 
      "deliveryCostOrShippingFee": 20, 
      "totalAmount": 530, 
      "pointRedemptionCashBackAmount": 0 
    } 
  ], 
  "reference": "Reference", 
  "sourceTransactionId": "primo_19091996", 
  "staffId": "admin01", 
  "transactionDate": "2022-12-31T03:07:45Z" 
}

HTTP Response

Successful Response

Model: Earn Points Response

Model: Response Data

Model: Point

Model: Transaction

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "memberNo": "M0000000001", 
    "orderNo": "OR0202303030001", 
    "points": [ 
      { 
        "balance": 1500, 
        "id": 1, 
        "name": "primo_point" 
      } 
    ], 
    "sourceTransactionId": "primo_19091996", 
    "transactionId": "6094ec405077595050e6d36e", 
    "transactions": [ 
      { 
        "earningOutcomeType": "Point", 
        "pointCurrencyId": 1, 
        "pointCurrencyCode": "POINT", 
        "pointCurrencyNameTh": "คะแนน", 
        "pointCurrencyNameEn": "Points", 
        "earnedPointAmount": 53, 
        "redeemedPointAmount": 0, 
        "expiredDate": "2025-12-31", 
        "sourceTransactionId": "primo_19091996", 
        "totalAmount": 53 
      } 
    ] 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP02", 
  "message": "SourceTransactionId is duplicated in loyalty program", 
  "data": null 
}

Status Codes

Error Codes

Void Earn Point

The CRM provider would need to call this endpoint to void an earned point transaction.

HTTP Request

POST /v1.3/points/void-earn

Request Header

Content Body

Content will be in JSON object format which begins with { and ends with }.

Sample Request

{ 
  "identifierField": "member_no", 
  "identifierValue": "M0000000001", 
  "earnSourceTransactionId": "primo_M0000000001", 
  "earnBillNoOrReceiptNo": "primo_19091996", 
  "remark": "void for reject order", 
  "staffId": "admin", 
  "transactionDate": "2022-12-31T03:07:45Z" 
}

HTTP Response

Successful Response

Model: Void Earn Response

Model: Response Data

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "memberNo": "M0000000001", 
    "earnSourceTransactionId": "primo_M0000000001", 
    "earnBillNoOrReceiptNo": "primo_19091996", 
    "totalSpending": 20, 
    "remark": "void for reject order", 
    "staffId": "admin" 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP13", 
  "message": "Earn transaction not found", 
  "data": null 
}

Status Codes

Error Codes

Redeem Points

The CRM provider would need to call this endpoint to create a redeem point transaction.

HTTP Request

POST /v1.3/points/redeem

Request Header

Content Body

Content will be in JSON object format which begins with { and ends with }.

Model: Redeem Point

Sample Request

{ 
  "memberNo": "M0000000001", 
  "sourceTransactionId": "primo_19091996", 
  "transactionDate": "2022-12-31T03:07:45Z", 
  "redeemPoints": [ 
    { 
      "pointCurrencyId": 1, 
      "value": 999 
    } 
  ], 
  "billNo": "812345678", 
  "remark": "redeem_from_yeti_mall", 
  "channelRef": "web_yetimall", 
  "staffId": "admin", 
  "ref1": "ref1", 
  "ref2": "ref2", 
  "ref3": "ref3" 
}

HTTP Response

Successful Response

Model: Redeem Response

Model: Response Data

Model: Redeemed Point

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "memberNo": "M0000000001", 
    "redeemPoints": [ 
      { 
        "pointCurrencyId": 1, 
        "value": 999 
      } 
    ], 
    "sourceTransactionId": "primo_19091996", 
    "transactionDate": "2022-12-31T03:07:45Z" 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP06", 
  "message": "Point not enough", 
  "data": null 
}

Status Codes

Error Codes

Void Point Earning

Reverses a previous point redemption transaction and restores the deducted points back to the member's balance.

HTTP Request

POST /v1.3/points/void-redeem

Request Header

Request Body

Content will be in JSON object format which begins with { and ends with }.

Validation Rules

• memberNo: Allow characters: A-Z, a-z, 0-9, _, - | Maximum length: 20 | Must not start with - | Must not end with _
• staffId: Allow characters: A-Z, a-z, 0-9, _, - | Length between 6 - 32 characters
• transactionDate: Format must be YYYY-MM-DDTHH:mm:ssZ (Example: 2022-12-31T03:05:23Z)

Sample Request

{ 
  "memberNo": "M0000000001", 
  "sourceTransactionId": "primo_20221231", 
  "transactionDate": "2022-12-31T03:05:23Z", 
  "staffId": "admin01", 
  "billNo": "primo_12334324", 
  "remark": "void redeem from portal", 
  "channelRef": "yetimall" 
}

HTTP Response

Successful Response

Model: Void Redeem Response

Model: Response Data

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "memberNo": "M0000000001", 
    "sourceTransactionId": "void_20221231", 
    "transactionDate": "2022-12-31T03:05:23Z", 
    "redeemSourceTransactionId": "primo_20221231", 
    "remark": "void redeem from portal" 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP11", 
  "message": "This transaction is already voided", 
  "data": null 
}

Status Codes

Error Codes

Validation Errors

[ 
  "[memberNo] should not be empty", 
  "[sourceTransactionId] should not be empty", 
  "[transactionDate] must be a valid datetime", 
  "[transactionDate] should not be empty", 
  "[staffId] should not be empty", 
  "[staffId] must match /regex/ format", 
  "[billNo] should not be empty", 
  "[channelRef] should not be empty", 
  "[remark] should not be empty" 
]

Verify Coupon

Verify coupon information for manual verification before mark used transaction

HTTP Request

GET /v1.3/transaction/coupon/verify?code={couponCode}&collectionId={collectionId}

Request Header

Query Parameters

Sample Request

GET /v1.3/transaction/coupon/verify?code=PRE-00012UU&collectionId=1

Sample Headers

{ 
  "authorization": "Bearer U2FsdGVkX1/PcsMSjH8TsFQqwj...", 
  "branch-code": "__default_branch__", 
  "brand-code": "__default_brand__", 
  "company-code": "__default_company__", 
  "session-id": "ES12qe213eqW2412", 
  "source-transaction-id": "abcDEF123HU1Kl", 
  "pos-id": "easy-restaurant" 
}

HTTP Response

Successful Response

Model: Verify Coupon Response

Response Data

Coupon Status mappings

Coupon Type mappings

Program Type mappings

Sample Success Response

{ 
  "successful": true, 
  "errorCode": "00", 
  "message": "Success", 
  "data": { 
    "couponOutcomeLogId": "65b75234cc765cd8dd8cc00e", 
    "couponId": 2131599, 
    "code": "qwert1uDF0MbnnI6", 
    "statusId": 2, 
    "statusName": "redeemed", 
    "collectionId": 6392, 
    "couponTypeId": 1, 
    "programType": "Privilege", 
    "campaignId": 6236, 
    "programId": 4351, 
    "programOutcomeConditionId": 4385, 
    "campaignOutcomeId": 6095, 
    "memberNo": "M0000054307", 
    "memberId": 54307, 
    "outcomeTransactionLogId": "65b75233cc765cd8dd8cc009", 
    "expirationDate": "2024-12-31T16:59:59.000+00:00", 
    "startDate": "2024-01-28T17:00:00.000+00:00", 
    "usedAt": null, 
    "redeemedAt": "2024-01-29T07:22:27.000Z", 
    "couponCollection": { 
      "id": 6392, 
      "name": "Super Coupon", 
      "refCode": "123456", 
      "descriptionTh": "Daily coupon", 
      "descriptionEn": "Daily coupon", 
      "imageTh": null, 
      "imageEn": null, 
      "status": 1, 
      "couponTypeId": 1, 
      "couponTypeNameTh": "คูปองทั่วไป", 
      "couponTypeNameEn": "Basic Coupon" 
    } 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP32", 
  "message": "Coupon not found", 
  "data": null 
}

Status Codes

Error Codes

Validation Errors

[ 
  "[collectionId] should not be empty", 
  "[code] should not be empty" 
]

Mark Used Privilege

Mark a redeemed coupon as used in the loyalty platform.

HTTP Request

POST /v1.3/privileges/mark-used

Request Header

Request Body

Coupons Object

Sample Request

Headers:

{ 
  "authorization": "Bearer U2FsdGVkX1/PcsMSjH8TsFQqwj...", 
  "branch-code": "__default_branch__", 
  "brand-code": "__default_brand__", 
  "company-code": "__default_company__", 
  "session-id": "ES12qe213eqW2412", 
  "source-transaction-id": "abcDEF123HU1Kl", 
  "pos-id": "easy-restaurant" 
}

Body:

{ 
  "memberNo": "M0000000001", 
  "coupons": [ 
    { 
      "collectionId": 12, 
      "code": "3ae43345t" 
    } 
  ] 
}

HTTP Response

Successful Response

Model: Mark Used Response

Sample Success Response

{ 
  "errorCode": "00", 
  "successful": true, 
  "message": "Success", 
  "httpStatus": 200, 
  "data": null 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP36", 
  "message": "Coupon has been used", 
  "data": null 
}

Status Codes

Error Codes

Validation Errors

[ 
  "[memberNo] must be a string", 
  "[memberNo] should not be empty", 
  "[coupons] must contain at least 1 elements", 
  "[coupons] must be an array", 
  "[collectionId] must be a number conforming to the specified constraints", 
  "[collectionId] should not be empty", 
  "[code] must be a string", 
  "[code] should not be empty" 
]

List Coupon Wallets

Retrieve coupon wallets for a member with filtering and pagination support.

HTTP Request

POST /v1/member/wallets

Request Header

Request Body

Coupon Outlet Object

Coupon Type Values

• basic_coupon : Basic coupon
• cash_coupon : Cash coupon
• discount_coupon : Discount coupon
• lucky_draw : Lucky draw
• mobile_top_up : Mobile top-up
• premium : Premium coupon
• product_and_service : Product and service

Display Status Values

• expired : Expired coupon
• redeemed : Redeemed coupon
• used : Used coupon
• using : Using coupon

Sample Request

Headers:

{ 
  "authorization": "Bearer U2FsdGVkX1/PcsMSjH8TsFQqwj...", 
  "session-id": "ES12qe213eqW2412" 
}

Body:

{ 
  "memberNo": "M0000000001", 
  "campaignCollectionSlugs": [ 
    "campaign_slug1", 
    "campaign_slug2" 
  ], 
  "couponOutlets": [ 
    { 
      "companyCode": "001", 
      "brandCode": "001", 
      "branchCode": "001" 
    } 
  ], 
  "couponType": [ 
    "basic_coupon", 
    "cash_coupon" 
  ], 
  "displayStatus": [ 
    "redeemed" 
  ], 
  "sort": "created_at", 
  "order": "ASC", 
  "offset": 0, 
  "limit": 10 
}

HTTP Response

Successful Response

Model: Coupon Wallet Response

Response Data Models

Meta Object

Items Object

Coupon Object

Campaign Object

Sample Success Response

{ 
  "errorCode": "00", 
  "successful": true, 
  "message": "Success", 
  "httpStatus": 200, 
  "data": { 
    "meta": { 
      "count": 1, 
      "offset": 0, 
      "limit": 10, 
      "total": 100 
    }, 
    "items": [ 
      { 
        "coupon": { 
          "collectionId": 1, 
          "couponId": 1, 
          "outcomeTransactionLogId": "681470e89f026b21e8b167fa", 
          "expirationDate": "2025-12-31T16:59:59.000+00:00", 
          "redeemedAt": "2025-12-31T16:59:59.000+00:00", 
          "startDate": "2025-12-31T16:59:59.000+00:00", 
          "statusId": 2, 
          "statusName": "redeemed", 
          "usedExpireDate": null, 
          "uniqueLink": "" 
        }, 
        "campaign": { 
          "id": 1, 
          "imageEn": "https://assets-b-ts-stable.primo-dev.com/8-ec30bfdf6807.jpg", 
          "imageTh": "", 
          "nameEn": "", 
          "nameTh": "ส่วนลดสินค้าที่เข้าร่วมรายการ 10%", 
          "campaignCollections": [ 
            { 
              "id": 1, 
              "slug": "campaign_slug1", 
              "nameTh": "", 
              "nameEn": "hot", 
              "isActive": true 
            } 
          ], 
          "campaignOutcome": { 
            "id": 1, 
            "nameEn": "coupon discount 10%", 
            "nameTh": "", 
            "conditionEn": "", 
            "conditionTh": "", 
            "descriptionEn": "", 
            "descriptionTh": "", 
            "outcomeTypeId": 1 
          } 
        } 
      } 
    ] 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "06", 
  "message": [ 
    "memberNo should not be empty", 
    "limit must not be less than 1" 
  ], 
  "data": null 
}

Status Codes

Error Codes

Validation Errors

[ 
  "memberNo should not be empty", 
  "memberNo must be a string", 
  "memberNo must be shorter than or equal to 255 characters", 
  "campaignCollectionSlugs should not be empty", 
  "each value in campaignCollectionSlugs should not be empty", 
  "each value in campaignCollectionSlugs must be a string", 
  "couponOutlets should not be empty", 
  "each value in couponOutlets must contain objects of CouponOutletFilter type", 
  "couponType should not be empty", 
  "each value in couponType should not be empty", 
  "each value in couponType must be one of the following values: basic_coupon, cash_coupon, discount_coupon, lucky_draw, mobile_top_up, premium, product_and_service", 
  "displayStatus should not be empty", 
  "each value in displayStatus should not be empty", 
  "each value in displayStatus must be one of the following values: expired, redeemed, used, using", 
  "limit must be an integer number", 
  "limit must not be less than 1", 
  "offset must be an integer number", 
  "offset must not be less than 0", 
  "order must be one of the following values: ASC, DESC", 
  "sort must be one of the following values: created_at, updated_at", 
  "branchCode should not be empty", 
  "branchCode must be a string", 
  "branchCode must be shorter than or equal to 255 characters", 
  "brandCode should not be empty", 
  "brandCode must be a string", 
  "brandCode must be shorter than or equal to 255 characters", 
  "companyCode should not be empty", 
  "companyCode must be a string", 
  "companyCode must be shorter than or equal to 255 characters" 
]

Get Coupon Wallet by Member

Retrieve a specific coupon wallet detail for a member by using memberNo and outcomeTransactionLogId.

HTTP Request

GET /v1/member/wallet?memberNo={memberNo}&outcomeTransactionLogId={outcomeTransactionLogId}&isIncludeOutlet={isIncludeOutlet}

Request Header

Query Parameters

Sample Request

GET /v1/member/wallet?memberNo=M0000000001&outcomeTransactionLogId=681470e89f026b21e8b167fa&isIncludeOutlet=false

Sample Headers

{ 
  "authorization": "Bearer U2FsdGVkX1/PcsMSjH8TsFQqwj...", 
  "session-id": "ES12qe213eqW2412" 
}

HTTP Response

Successful Response

Model: Get Coupon Wallet Response

Response Data Details

Coupon

CouponOutlets

Campaign

Coupon Status Mapping

Sample Success Response

{ 
  "errorCode": "00", 
  "successful": true, 
  "message": "Success", 
  "httpStatus": 200, 
  "data": { 
    "coupon": { 
      "code": "D1y5tpCZs1", 
      "collectionId": 1, 
      "couponId": 1, 
      "outcomeTransactionLogId": "681470e89f026", 
      "expirationDate": "2025-12-31T16:59:59.000+00:00", 
      "redeemedAt": "2025-12-31T16:59:59.000+00:00", 
      "startDate": "2025-12-31T16:59:59.000+00:00", 
      "statusId": 2, 
      "statusName": "redeemed", 
      "usedExpireDate": null, 
      "uniqueLink": "", 
      "couponOutlets": [ 
        { 
          "companyCode": "001", 
          "brandCode": "001", 
          "branchCode": "001" 
        } 
      ] 
    }, 
    "campaign": { 
      "id": 1, 
      "imageEn": "https://assets-b-ts-stable.primo-dev.com/8-ec30bfdf6807.jpg", 
      "imageTh": "", 
      "nameEn": "", 
      "nameTh": "ส่วนลดสินค้าที่เข้าร่วมรายการ 10%", 
      "campaignCollections": [ 
        { 
          "id": 1, 
          "slug": "campaign_slug1", 
          "nameTh": "", 
          "nameEn": "hot", 
          "isActive": true 
        } 
      ], 
      "campaignOutcome": { 
        "id": 1, 
        "nameEn": "coupon discount 10%", 
        "nameTh": "", 
        "conditionEn": "", 
        "conditionTh": "", 
        "descriptionEn": "", 
        "descriptionTh": "", 
        "outcomeTypeId": 1 
      }, 
      "programOutcomeCondition": { 
        "id": 1, 
        "programId": 1, 
        "programOutcomeAcceptanceId": 1, 
        "programOutcomeAcceptanceTypeId": 1, 
        "programOutcomeCouponDisplayTypeIds": [1, 2, 3, 4], 
        "programOutcomeMarkUse": { 
          "id": 1, 
          "markUseTypeId": 1, 
          "isOwnerOnly": false, 
          "unitTypeId": 1, 
          "validWithinValue": 1 
        } 
      } 
    } 
  } 
}

Error Response

{ 
  "successful": false, 
  "errorCode": "OP32", 
  "message": "Coupon not found", 
  "data": null 
}

Status Codes

Error Codes

Validation Errors

[ 
  "memberNo should not be empty", 
  "memberNo must be shorter than or equal to 255 characters", 
  "memberNo must be a string", 
  "outcomeTransactionLogId should not be empty", 
  "outcomeTransactionLogId must be shorter than or equal to 255 characters", 
  "outcomeTransactionLogId must be a string", 
  "isIncludeOutlet must be one of the following values: true, false" 
]