All Collections
Develop
PassKit API
Coupon Protocol: Filtering, Listing and Counting by API
Coupon Protocol: Filtering, Listing and Counting by API

Filter campaigns, offers and coupons by API.

Danny Allen avatar
Written by Danny Allen
Updated over a week ago

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.

Did this answer your question?