Filters for Coupon Protocol

Filter Campaigns

You can filter campaigns with following fields.

name (name of campaigns) - string value
ianaTimezone (campaign timezone) - string value e.g. America/New_York, Asia/Hong_Kong
created (created date of campaigns) - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800
updated (last updated date of campaigns) - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800

Operators:

eq - equal
gt - greater than
lt - less than
gte - greater than or equal to
lte - less than or equal to
like - contain a value

List campaigns endpoint

POST https://api.pub1.passkit.io/coupon/singleUse/campaigns/list

Examples: POST request payload for filter coupons

Filter campaigns with America/New_York timezone.

{
   "limit": 100,
   "offset": 0,
   "orderBy": "created",
   "orderAsc": true,
   "filterGroups": [{
      "condition": "AND",
      "fieldFilters": [{
         "filterField": "ianaTimezone",
         "filterValue": "America/New_York",
         "filterOperator": "eq"
      }]
   }]
}

Filter campaigns created in March 2020.

{
   "limit": 100,
   "offset": 0,
   "orderBy": "created",
   "orderAsc": true,
   "filterGroups": [{
      "condition": "AND",
      "fieldFilters": [{
         "filterField": "created",
         "filterValue": "2020-03-01T00:00:00Z",
         "filterOperator": "gte"
      },{
         "filterField": "created",
         "filterValue": "2020-04-01T00:00:00Z",
         "filterOperator": "lt"
      }]
   }]
}

Filter campaigns which as timezone America/New_York OR Asia/Hong_Kong.

{
   "limit": 100,
   "offset": 0,
   "orderBy": "created",
   "orderAsc": true,
   "filterGroups": [{
      "condition": "OR",
      "fieldFilters": [{
         "filterField": "ianaTimezone",
         "filterValue": "America/New_York",
         "filterOperator": "eq"
      },{
         "filterField": "ianaTimezone",
         "filterValue": "Asia/Hong_Kong",
         "filterOperator": "eq"
      }]
   }]
}

Filter Offers

You can filter offers with following fields.

id (offer id) - string value
offerTitle - strings value
offerShortTitle - string value
issueStartDate - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800
issueEndDate - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800
created (created date of offers) - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800
updated (last updated date of offers) - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800
ianaTimezone (campaign timezone) - string value e.g. Australia/Sydney, America/Sao_Paulo

List offers endpoint

POST https://api.pub1.passkit.io/coupon/singleUse/offers/list

Examples: POST payload for filtering offers

Filter offers which contain a word 'discount' in offer title.

{
   "campaignId": "your_campagin_id",
   "filters": {
      "limit": 100,
      "offset": 0,
      "orderBy": "created",
      "orderAsc": true,
      "filterGroups": [{
         "condition": "AND",
         "fieldFilters": [{
            "filterField": "offerTitle",
            "filterValue": "discount",
            "filterOperator": "like"
         }]
      }]
   }
}

Filter offers with issueStartDate after 1st May 2020 AND before 31 May 2020.

{
      "campaignId": "your_campagin_id",   
      "filters": {
      "limit": 100,
      "offset": 0,
      "orderBy": "created",
      "orderAsc": true,
      "filterGroups": [{
         "condition": "AND",
         "fieldFilters": [{
            "filterField": "issueStartDate",
            "filterValue": "2020-05-01T00:00:00Z",
            "filterOperator": "gt"
         },{
            "filterField": "issueStartDate",
            "filterValue": "2020-05-31T23:59:59Z",
            "filterOperator": "lt"
         }]
      }]
   }
}

Filter offers with offerShortTitle contains a keyword 'discount' OR 'special'.

{
   "campaignId": "your_campagin_id",
   "filters": {
      "limit": 100,
      "offset": 0,
      "orderBy": "created",
      "orderAsc": true,
      "filterGroups": [{
         "condition": "OR",
         "fieldFilters": [{
            "filterField": "offerShortTitle",
            "filterValue": "discount",
            "filterOperator": "like"
         },{
            "filterField": "offerShortTitle",
            "filterValue": "special",
            "filterOperator": "eq"
         }]
      }]
   }
}

Filter Coupons

Step 1: Get a Campaign ID
Step 2: Set a filter condition
Step 3: Make an API call

Step 1 : Get a Campaign ID

You can grab you Campaign ID from Settings Page.

Step 2: Set a filter condition

You can filter coupons with following fields and values:

externalId (external id of coupon) - string value
offerId (offer id which coupon belongs to) - string value
firstName (first name of coupon holders) - string value
lastName (last name of coupon holders) - string value
gender (gender of coupon holders) - NOT_KNOWN, FEMALE or MALE
dataOfBirth (DOB of coupon holders) - ISO8601 date e.g. 2020-01-21
email (email of coupon holders) - string value
mobileNumber (mobile of coupon holders) - string value e.g. +85298001243
displayName (display name of coupon holders) - string value
birthMonth (birthday month of coupon holders) - month e.g. april, october
sku (sku of coupons) - string value
optOut (marketing promotion options) - true or false
passStatus (status of coupon pass) - PASS_ISSUED, PASS_INSTALLED, PASS_UNINSTALLED or PASS_INVALIDATED
status (redemption status) - UNREDEEMED or REDEEMED
expiryDate (expiry date of coupons) - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800
created (coupon issued date) - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800
updated (the last updated date) - RFC3339 or timestamp e.g. 2020-01-21T00:00:00Z, 1579564800

Operators:

eq - equal
gt - greater than
lt - less than
gte - greater than or equal to
lte - less than or equal to
like - contain a value

Step 3: Make an API call

LIST coupons endpoint

POST https://api.pub1.passkit.io/coupon/singleUse/coupons/list/your_campagin_id

COUNT coupons endpoint

POST https://api.pub1.passkit.io/coupon/singleUse/coupons/count/your_campagin_id

Examples: POST request payload for filter coupons

Filter coupons which has been installed on mobile.

{
   "filters": {
      "limit": 100,
      "offset": 0,
      "orderBy": "created",
      "orderAsc": true,
      "filterGroups": [{
         "condition": "AND",
         "fieldFilters": [{
            "filterField": "passStatus",
            "filterValue": "PASS_INSTALLED",
            "filterOperator": "eq"
         }]
      }]
   }
}

Filter redeemed coupons.

{
   "filters": {
      "limit": 100,
      "offset": 0,
      "orderBy": "created",
      "orderAsc": true,
      "filterGroups": [{
         "condition": "AND",
         "fieldFilters": [{
            "filterField": "status",
            "filterValue": "REDEEMED",
            "filterOperator": "eq"
         }]
      }]
   }
}

Filter coupons created between 2020-01-01 AND 2020-01-31.

{
   "filters": {
      "limit": 100,
      "offset": 0,
      "orderBy": "created",
      "orderAsc": true,
      "filterGroups": [{
         "condition": "AND",
         "fieldFilters": [{
            "filterField": "created",
            "filterValue": "2020-01-01",
            "filterOperator": "gte"
         },{
            "filterField": "created",
            "filterValue": "2020-01-31",
            "filterOperator": "lte"
         }]
      }]
   }
}

Filter coupons with offer id A OR B.

{
   "filters": {
      "limit": 100,
      "offset": 0,
      "orderBy": "created",
      "orderAsc": true,
      "filterGroups": [{
         "condition": "OR",
         "fieldFilters": [{
            "filterField": "offerId",
            "filterValue": "3413Xbd46C4eKNbxUeNX0g",
            "filterOperator": "eq"
         },{
            "filterField": "offerId",
            "filterValue": "7MfMpbCecTdJnWnM37HcnM",
            "filterOperator": "eq"
         }]
      }]
   }
}

Filter coupons with ( sku disc5 OR disc10 ) AND status is unredeemed.

{
   "filters": {
      "limit": 100,
      "offset": 0,
      "orderBy": "created",
      "orderAsc": true,
      "filterGroups": [{
         "condition": "OR",
         "fieldFilters": [{
            "filterField": "sku",
            "filterValue": "disc5",
            "filterOperator": "eq"
         },{
            "filterField": "sku",
            "filterValue": "disc10",
            "filterOperator": "eq"
         }]
      },{
         "condition": "AND",
         "fieldFilters": [{
            "filterField": "status",
            "filterValue": "UNREDEEMED",
            "filterOperator": "eq"
         }]
      }]
   }
}

Note: Limit has maximum limit of 1000 for REST API call. Unlimited Limit is available for gRPC request.

Membership Protocol: Filtering, Listing and Counting by API

Pass Templates, Locations, Beacons & Links: Filtering, Listing and Counting by API