Privilege

List privileges for the specified pass id.

get

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass id.

tenantIdstringRequired

Responses

200

Privileges returned

text/plainapplication/jsontext/json

Represents a persisted privilege with a required unique identifier.

404

Pass not found

text/plainapplication/jsontext/json

get

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

HTTPcURLJavaScriptPython

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": null
      },
      "callToAction": {
        "title": {
          "value": null,
          "values": null
        },
        "link": null
      }
    },
    "data": {
      "value": null,
      "movements": [
        {
          "movementId": null,
          "date": "2026-03-05T00:03:48.011Z",
          "value": 1,
          "remarks": null
        }
      ],
      "content": null
    },
    "deletionDate": null
  }
]

Create a privilege for the specified pass id.

post

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass id.

tenantIdstringRequired

Body

application/jsontext/jsonapplication/*+json

Request model to create a new privilege.

Responses

200

Privilege queued

No content

404

Pass not found

text/plainapplication/jsontext/json

post

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

HTTPcURLJavaScriptPython

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: 816

{
  "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": null
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": null
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": null,
        "date": "2026-03-05T00:03:48.011Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": null
}

application/jsontext/jsonapplication/*+json

No content

Retrieve a privilege for a specific pass.

get

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass identifier.

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Responses

200

Privilege returned

text/plainapplication/jsontext/json

Represents a persisted privilege with a required unique identifier.

404

Pass or privilege not found

text/plainapplication/jsontext/json

get

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

HTTPcURLJavaScriptPython

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

{
  "privilegeId": null,
  "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": null
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": null
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": null,
        "date": "2026-03-05T00:03:48.011Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": null
}

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

put

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass id.

privilegeIdstringRequired

Unique identifier of the privilege to upsert.

tenantIdstringRequired

Body

application/jsontext/jsonapplication/*+json

Request model to patch an existing privilege.

Responses

200

Privilege upsert queued or applied

No content

404

Pass not found

text/plainapplication/jsontext/json

put

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

HTTPcURLJavaScriptPython

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: 816

{
  "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": null
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": null
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": null,
        "date": "2026-03-05T00:03:48.011Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": null
}

application/jsontext/jsonapplication/*+json

No content

Delete a privilege for a specific pass.

delete

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

Pass identifier.

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Responses

204

Privilege deleted

404

Pass or privilege not found

text/plainapplication/jsontext/json

delete

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

HTTPcURLJavaScriptPython

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

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

Responses

200

Privileges returned

text/plainapplication/jsontext/json

Represents a persisted privilege with a required unique identifier.

404

Pass not found

text/plainapplication/jsontext/json

get

/api/{tenantId}/passes/privileges

HTTPcURLJavaScriptPython

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": null
      },
      "callToAction": {
        "title": {
          "value": null,
          "values": null
        },
        "link": null
      }
    },
    "data": {
      "value": null,
      "movements": [
        {
          "movementId": null,
          "date": "2026-03-05T00:03:48.011Z",
          "value": 1,
          "remarks": null
        }
      ],
      "content": null
    },
    "deletionDate": null
  }
]

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

post

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

Body

application/jsontext/jsonapplication/*+json

Request model to create a new privilege.

Responses

200

Privilege queued

No content

404

Pass not found

text/plainapplication/jsontext/json

post

/api/{tenantId}/passes/privileges

HTTPcURLJavaScriptPython

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

{
  "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": null
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": null
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": null,
        "date": "2026-03-05T00:03:48.011Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": null
}

application/jsontext/jsonapplication/*+json

No content

Retrieve a privilege by its id.

get

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Responses

200

Privilege returned

text/plainapplication/jsontext/json

Represents a persisted privilege with a required unique identifier.

404

Privilege not found

text/plainapplication/jsontext/json

get

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

HTTPcURLJavaScriptPython

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

{
  "privilegeId": null,
  "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": null
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": null
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": null,
        "date": "2026-03-05T00:03:48.011Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": null
}

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

put

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

privilegeIdstringRequired

Unique identifier of the privilege to upsert.

tenantIdstringRequired

Query parameters

Body

application/jsontext/jsonapplication/*+json

Request model to patch an existing privilege.

Responses

200

Privilege upsert queued or applied

No content

404

Pass not found

text/plainapplication/jsontext/json

put

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

HTTPcURLJavaScriptPython

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: 816

{
  "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": null
    },
    "callToAction": {
      "title": {
        "value": null,
        "values": null
      },
      "link": null
    }
  },
  "data": {
    "value": null,
    "movements": [
      {
        "movementId": null,
        "date": "2026-03-05T00:03:48.011Z",
        "value": 1,
        "remarks": null
      }
    ],
    "content": null
  },
  "deletionDate": null
}

application/jsontext/jsonapplication/*+json

No content

Delete a privilege by its id.

delete

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Responses

204

Privilege deleted

404

Privilege not found

text/plainapplication/jsontext/json

delete

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

HTTPcURLJavaScriptPython

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

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/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

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

privilegeIdstringRequired

Privilege identifier.

tenantIdstringRequired

Body

application/jsontext/jsonapplication/*+json

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

text/plainapplication/jsontext/json

Response payload after a movement is created.

movementIdstring · nullableOptional

400

MovementValue is zero

text/plainapplication/jsontext/json

404

Privilege not found

text/plainapplication/jsontext/json

409

Current value does not match OldValue (concurrency conflict)

text/plainapplication/jsontext/json

post

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

HTTPcURLJavaScriptPython

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
}

application/jsontext/jsonapplication/*+json

{
  "movementId": null
}