Privilege

List privileges for the specified pass id.

get

/api/{tenantId}/passes/{passId}/privileges

Retrieves all privileges for a specific pass using its identifier. Convenience endpoint when the pass ID is already known.

Authorization

Requires Pass.Read scope.

Sorting

Privileges are returned in priority order (highest to lowest).

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass id.

tenantIdstringRequired

Responses

200

Privileges returned

Represents a persisted privilege with a required unique identifier.

externalIdstring · min: 1 · max: 100 · nullableOptional

External identifier for the privilege in the source system.

priorityinteger · nullableOptional

Priority of the privilege. Larger numbers indicate higher importance (e.g., 100 > 10).

typestring · enumRequired

The functional type of the privilege.

Possible values:

deletionDateone ofOptional

The timestamp at which this privilege should be removed from the system. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings.

string · date-timeOptional

integer · int64Optional

privilegeIdstringRequired

Unique identifier of the privilege (unique across all passes within the tenant).

404

Pass not found

get/api/{tenantId}/passes/{passId}/privileges

GET /api/{tenantId}/passes/{passId}/privileges HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "externalId": null,
    "priority": null,
    "origin": {
      "externalId": null,
      "generator": null,
      "processId": null
    },
    "type": "OneTime",
    "categories": [
      "Other"
    ],
    "content": {
      "title": {
        "value": null,
        "values": null
      },
      "description": {
        "value": null,
        "values": null
      }
    },
    "appearance": {
      "mainImageUrl": {
        "value": null,
        "values": null
      },
      "thumbnailUrl": {
        "value": null,
        "values": null
      },
      "backgroundColor": null,
      "foregroundColor": null
    },
    "links": {
      "legalInformation": {
        "title": {
          "value": null,
          "values": null
        },
        "link": "https://example.com"
      },
      "callToAction": {
        "title": {
          "value": null,
          "values": null
        },
        "link": "https://example.com"
      }
    },
    "data": {
      "value": null,
      "movements": [
        {
          "movementId": "text",
          "date": "2026-07-12T17:21:03.929Z",
          "value": 1,
          "remarks": null
        }
      ],
      "content": null
    },
    "deletionDate": "2026-07-12T17:21:03.929Z"
  }
]

Create a privilege for the specified pass id.

post

/api/{tenantId}/passes/{passId}/privileges

Creates a new privilege using the pass identifier directly. Use the PUT variants with a privilegeId in the route for idempotent upsert semantics. This is a convenience endpoint for scenarios where the pass ID is already known.

Authorization

Requires Pass.Write scope.

Behavior

Same as the identifiers-based variant but uses a path parameter instead of query identifiers.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass id.

tenantIdstringRequired

Body

Request model to create a new privilege.

externalIdstring · min: 1 · max: 100 · nullableOptional

External identifier for the privilege in the source system.

priorityinteger · nullableOptional

Priority of the privilege. Larger numbers indicate higher importance.

deletionDateone ofOptional

string · date-timeOptional

integer · int64Optional

typestring · enumRequired

The functional type of the privilege (required for new privileges).

Possible values:

Responses

200

Privilege queued

No content

404

Pass not found

post/api/{tenantId}/passes/{passId}/privileges

POST /api/{tenantId}/passes/{passId}/privileges HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 874

{
  "type": "OneTime",
  "options": {
    "correlationId": null,
    "notification": {
      "content": null,
      "localizedContent": null,
      "options": {
        "updateData": false,
        "correlationId": null
      }
    }
  },
  "externalId": null,
  "priority": null,
  "origin": {
    "externalId": null,
    "generator": null,
    "processId": null
  },
  "categories": [
    "Other"
  ],
  "content": {
    "title": {
      "value": null,
      "values": null
    },
    "description": {
      "value": null,
      "values": null
    }
  },
  "appearance": {
    "mainImageUrl": {
      "value": null,
      "values": null
    },
    "thumbnailUrl": {
      "value": null,
      "values": null
    },
    "backgroundColor": null,
    "foregroundColor": null
  },
  "links": {
    "legalInformation": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": "text",
        "date": "2026-07-12T17:21:03.929Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": "2026-07-12T17:21:03.929Z"
}

No content

Retrieve a privilege for a specific pass.

get

/api/{tenantId}/passes/{passId}/privileges/{privilegeId}

Fetches a single privilege belonging to a specific pass. Ensures both the pass and privilege exist and are correctly associated.

Authorization

Requires Pass.Read scope.

Validation

Returns 404 if either the pass or the privilege is missing, or if the privilege does not belong to the specified pass.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass identifier.

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Responses

200

Privilege returned

Represents a persisted privilege with a required unique identifier.

externalIdstring · min: 1 · max: 100 · nullableOptional

External identifier for the privilege in the source system.

priorityinteger · nullableOptional

Priority of the privilege. Larger numbers indicate higher importance (e.g., 100 > 10).

typestring · enumRequired

The functional type of the privilege.

Possible values:

deletionDateone ofOptional

string · date-timeOptional

integer · int64Optional

privilegeIdstringRequired

Unique identifier of the privilege (unique across all passes within the tenant).

404

Pass or privilege not found

get/api/{tenantId}/passes/{passId}/privileges/{privilegeId}

GET /api/{tenantId}/passes/{passId}/privileges/{privilegeId} HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "privilegeId": "text",
  "externalId": null,
  "priority": null,
  "origin": {
    "externalId": null,
    "generator": null,
    "processId": null
  },
  "type": "OneTime",
  "categories": [
    "Other"
  ],
  "content": {
    "title": {
      "value": null,
      "values": null
    },
    "description": {
      "value": null,
      "values": null
    }
  },
  "appearance": {
    "mainImageUrl": {
      "value": null,
      "values": null
    },
    "thumbnailUrl": {
      "value": null,
      "values": null
    },
    "backgroundColor": null,
    "foregroundColor": null
  },
  "links": {
    "legalInformation": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": "text",
        "date": "2026-07-12T17:21:03.929Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": "2026-07-12T17:21:03.929Z"
}

Upsert (idempotent) a privilege for the specified pass id.

put

/api/{tenantId}/passes/{passId}/privileges/{privilegeId}

Creates or updates a privilege with the specified privilegeId for the given pass. This endpoint is idempotent: repeated calls with the same payload produce the same result.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass id.

privilegeIdstringRequired

Unique identifier of the privilege to upsert.

tenantIdstringRequired

Body

Request model to patch an existing privilege.

externalIdstring · min: 1 · max: 100 · nullableOptional

External identifier for the privilege in the source system.

priorityinteger · nullableOptional

Priority of the privilege. Larger numbers indicate higher importance.

deletionDateone ofOptional

string · date-timeOptional

integer · int64Optional

typestring · enumOptional

The functional type of the privilege (optional for patches).

Possible values:

Responses

200

Privilege upsert queued or applied

No content

404

Pass not found

put/api/{tenantId}/passes/{passId}/privileges/{privilegeId}

PUT /api/{tenantId}/passes/{passId}/privileges/{privilegeId} HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 874

{
  "type": "OneTime",
  "options": {
    "correlationId": null,
    "notification": {
      "content": null,
      "localizedContent": null,
      "options": {
        "updateData": false,
        "correlationId": null
      }
    }
  },
  "externalId": null,
  "priority": null,
  "origin": {
    "externalId": null,
    "generator": null,
    "processId": null
  },
  "categories": [
    "Other"
  ],
  "content": {
    "title": {
      "value": null,
      "values": null
    },
    "description": {
      "value": null,
      "values": null
    }
  },
  "appearance": {
    "mainImageUrl": {
      "value": null,
      "values": null
    },
    "thumbnailUrl": {
      "value": null,
      "values": null
    },
    "backgroundColor": null,
    "foregroundColor": null
  },
  "links": {
    "legalInformation": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": "text",
        "date": "2026-07-12T17:21:03.929Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": "2026-07-12T17:21:03.929Z"
}

No content

Delete a privilege for a specific pass.

delete

/api/{tenantId}/passes/{passId}/privileges/{privilegeId}

Removes a privilege from a specific pass. Both the pass and privilege must exist.

Authorization

Requires Pass.Write scope.

Scope

This operation only affects the privilege with the specified pass.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass identifier.

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Responses

204

Privilege deleted

No content

404

Pass or privilege not found

delete/api/{tenantId}/passes/{passId}/privileges/{privilegeId}

DELETE /api/{tenantId}/passes/{passId}/privileges/{privilegeId} HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

List privileges for the pass resolved from identifiers.

get

/api/{tenantId}/passes/privileges

Retrieves all privileges associated with a pass using query identifiers. Privileges are sorted by priority (highest first) and movements within each privilege are ordered by date (oldest first).

Authorization

Requires Pass.Read scope.

Use Cases

Display available offers and benefits to the pass holder
Check current loyalty balance or punch card progress
Verify privilege availability before redemption

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

Responses

200

Privileges returned

Represents a persisted privilege with a required unique identifier.

externalIdstring · min: 1 · max: 100 · nullableOptional

External identifier for the privilege in the source system.

priorityinteger · nullableOptional

Priority of the privilege. Larger numbers indicate higher importance (e.g., 100 > 10).

typestring · enumRequired

The functional type of the privilege.

Possible values:

deletionDateone ofOptional

string · date-timeOptional

integer · int64Optional

privilegeIdstringRequired

Unique identifier of the privilege (unique across all passes within the tenant).

404

Pass not found

get/api/{tenantId}/passes/privileges

GET /api/{tenantId}/passes/privileges HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "externalId": null,
    "priority": null,
    "origin": {
      "externalId": null,
      "generator": null,
      "processId": null
    },
    "type": "OneTime",
    "categories": [
      "Other"
    ],
    "content": {
      "title": {
        "value": null,
        "values": null
      },
      "description": {
        "value": null,
        "values": null
      }
    },
    "appearance": {
      "mainImageUrl": {
        "value": null,
        "values": null
      },
      "thumbnailUrl": {
        "value": null,
        "values": null
      },
      "backgroundColor": null,
      "foregroundColor": null
    },
    "links": {
      "legalInformation": {
        "title": {
          "value": null,
          "values": null
        },
        "link": "https://example.com"
      },
      "callToAction": {
        "title": {
          "value": null,
          "values": null
        },
        "link": "https://example.com"
      }
    },
    "data": {
      "value": null,
      "movements": [
        {
          "movementId": "text",
          "date": "2026-07-12T17:21:03.929Z",
          "value": 1,
          "remarks": null
        }
      ],
      "content": null
    },
    "deletionDate": "2026-07-12T17:21:03.929Z"
  }
]

Create a privilege for the pass identified by the supplied identifiers.

post

/api/{tenantId}/passes/privileges

Creates a new privilege for the specified pass. Use the PUT variants with a privilegeId in the route for idempotent upsert semantics. Privileges represent benefits, offers, or entitlements tied to a pass.

Authorization

Requires Pass.Write scope.

Operation

When a privilege is applied, the system queues it for processing. Optional notification can be sent to the pass holder upon application.

Use Cases

Adding loyalty points or rewards
Issuing promotional offers
Granting membership benefits

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

Body

Request model to create a new privilege.

externalIdstring · min: 1 · max: 100 · nullableOptional

External identifier for the privilege in the source system.

priorityinteger · nullableOptional

Priority of the privilege. Larger numbers indicate higher importance.

deletionDateone ofOptional

string · date-timeOptional

integer · int64Optional

typestring · enumRequired

The functional type of the privilege (required for new privileges).

Possible values:

Responses

200

Privilege queued

No content

404

Pass not found

post/api/{tenantId}/passes/privileges

POST /api/{tenantId}/passes/privileges HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 874

{
  "type": "OneTime",
  "options": {
    "correlationId": null,
    "notification": {
      "content": null,
      "localizedContent": null,
      "options": {
        "updateData": false,
        "correlationId": null
      }
    }
  },
  "externalId": null,
  "priority": null,
  "origin": {
    "externalId": null,
    "generator": null,
    "processId": null
  },
  "categories": [
    "Other"
  ],
  "content": {
    "title": {
      "value": null,
      "values": null
    },
    "description": {
      "value": null,
      "values": null
    }
  },
  "appearance": {
    "mainImageUrl": {
      "value": null,
      "values": null
    },
    "thumbnailUrl": {
      "value": null,
      "values": null
    },
    "backgroundColor": null,
    "foregroundColor": null
  },
  "links": {
    "legalInformation": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": "text",
        "date": "2026-07-12T17:21:03.929Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": "2026-07-12T17:21:03.929Z"
}

No content

Retrieve a privilege by its id.

get

/api/{tenantId}/passes/privileges/{privilegeId}

Fetches detailed information about a specific privilege across all passes in the tenant. Returns complete privilege metadata including content, appearance, and current state.

Authorization

Requires Pass.Read scope.

Use Cases

View privilege details for display or validation
Check privilege expiration or availability status
Retrieve localized content for multiple languages

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Responses

200

Privilege returned

Represents a persisted privilege with a required unique identifier.

externalIdstring · min: 1 · max: 100 · nullableOptional

External identifier for the privilege in the source system.

priorityinteger · nullableOptional

Priority of the privilege. Larger numbers indicate higher importance (e.g., 100 > 10).

typestring · enumRequired

The functional type of the privilege.

Possible values:

deletionDateone ofOptional

string · date-timeOptional

integer · int64Optional

privilegeIdstringRequired

Unique identifier of the privilege (unique across all passes within the tenant).

404

Privilege not found

get/api/{tenantId}/passes/privileges/{privilegeId}

GET /api/{tenantId}/passes/privileges/{privilegeId} HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "privilegeId": "text",
  "externalId": null,
  "priority": null,
  "origin": {
    "externalId": null,
    "generator": null,
    "processId": null
  },
  "type": "OneTime",
  "categories": [
    "Other"
  ],
  "content": {
    "title": {
      "value": null,
      "values": null
    },
    "description": {
      "value": null,
      "values": null
    }
  },
  "appearance": {
    "mainImageUrl": {
      "value": null,
      "values": null
    },
    "thumbnailUrl": {
      "value": null,
      "values": null
    },
    "backgroundColor": null,
    "foregroundColor": null
  },
  "links": {
    "legalInformation": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": "text",
        "date": "2026-07-12T17:21:03.929Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": "2026-07-12T17:21:03.929Z"
}

Upsert (idempotent) a privilege for the pass identified by the supplied identifiers.

put

/api/{tenantId}/passes/privileges/{privilegeId}

Creates or updates a privilege with the specified privilegeId for the resolved pass. This endpoint is idempotent: repeated calls with the same payload produce the same result.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

privilegeIdstringRequired

Unique identifier of the privilege to upsert.

tenantIdstringRequired

Query parameters

Body

Request model to patch an existing privilege.

externalIdstring · min: 1 · max: 100 · nullableOptional

External identifier for the privilege in the source system.

priorityinteger · nullableOptional

Priority of the privilege. Larger numbers indicate higher importance.

deletionDateone ofOptional

string · date-timeOptional

integer · int64Optional

typestring · enumOptional

The functional type of the privilege (optional for patches).

Possible values:

Responses

200

Privilege upsert queued or applied

No content

404

Pass not found

put/api/{tenantId}/passes/privileges/{privilegeId}

PUT /api/{tenantId}/passes/privileges/{privilegeId} HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 874

{
  "type": "OneTime",
  "options": {
    "correlationId": null,
    "notification": {
      "content": null,
      "localizedContent": null,
      "options": {
        "updateData": false,
        "correlationId": null
      }
    }
  },
  "externalId": null,
  "priority": null,
  "origin": {
    "externalId": null,
    "generator": null,
    "processId": null
  },
  "categories": [
    "Other"
  ],
  "content": {
    "title": {
      "value": null,
      "values": null
    },
    "description": {
      "value": null,
      "values": null
    }
  },
  "appearance": {
    "mainImageUrl": {
      "value": null,
      "values": null
    },
    "thumbnailUrl": {
      "value": null,
      "values": null
    },
    "backgroundColor": null,
    "foregroundColor": null
  },
  "links": {
    "legalInformation": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": "https://example.com"
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": "text",
        "date": "2026-07-12T17:21:03.929Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": "2026-07-12T17:21:03.929Z"
}

No content

Delete a privilege by its id.

delete

/api/{tenantId}/passes/privileges/{privilegeId}

Removes a privilege from the system entirely. The privilege is deleted across all passes it may be associated with.

Authorization

Requires Pass.Write scope.

Irreversibility

This operation is permanent. The privilege cannot be recovered after deletion.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Responses

204

Privilege deleted

No content

404

Privilege not found

delete/api/{tenantId}/passes/privileges/{privilegeId}

DELETE /api/{tenantId}/passes/privileges/{privilegeId} HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Apply a movement (transaction) to a privilege's value and return the created movement identifier.

post

/api/{tenantId}/passes/privileges/{privilegeId}/movements

Records a change to a privilege's value (redemption, adjustment, issuance). Movements are tracked in the privilege's history for audit purposes and form the basis for computing current value.

Authorization

Requires Pass.Write scope.

Concurrency Control

The OldValue parameter enables optimistic locking with server-side validation. The handler compares the expected value (OldValue) to the current sum with epsilon tolerance (±0.0001). This prevents race conditions when multiple clients attempt simultaneous updates. If values differ beyond tolerance, returns 409 Conflict; if privilege is missing, returns 404 Not Found.

Use Cases

Redeeming points or stamps (negative movement)
Issuing or adjusting loyalty balance (positive movement)
Applying promotional adjustments

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2implicitRequired

Authorization URL:

Path parameters

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Body

Request model to apply a movement (transaction) to a privilege's value.

oldValuenumber · doubleRequired

The expected sum of all movement values before this update. Used for optimistic concurrency control with server-side validation in the handler. If the current value differs, the request is rejected (409 Conflict).

movementValuenumber · doubleRequired

The movement value to apply. Cannot be zero. Positive for issuance/award, negative for redemption/usage. Fractional values are supported for progress-based privileges (e.g., 0.5 for half a stamp).

remarksstring · min: 1 · max: 500 · nullableOptional

Optional remarks or debug information about this movement.

Responses

200

Movement applied successfully

Response payload after a movement is created.

movementIdstringOptional

400

MovementValue is zero

404

Privilege not found

409

Current value does not match OldValue (concurrency conflict)

post/api/{tenantId}/passes/privileges/{privilegeId}/movements

POST /api/{tenantId}/passes/privileges/{privilegeId}/movements HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "oldValue": 1,
  "movementValue": 1,
  "remarks": null
}

{
  "movementId": "text"
}

Last updated 5 days ago