{ "openapi": "3.0.1", "info": { "title": "Stell API", "description": "Create and manage passes for Apple Wallet and Google Wallet. One API for loyalty programs, membership cards, tickets, and more.", "termsOfService": "https://getstell.com/terms", "contact": { "name": "Stell API Support", "url": "https://getstell.com/about?topic=Technical%20Support#contact", "email": "hello@getstell.com" }, "version": "2026-09-15T08:33:18Z" }, "servers": [ { "url": "https://api.platform.getstell.com", "description": "Production API" } ], "tags": [ { "name": "Companies", "description": "Manage companies at the top of your tenant hierarchy." }, { "name": "Merchants", "description": "Manage brands and business units within companies." }, { "name": "Stores", "description": "Manage store locations and customer touchpoints." }, { "name": "Programs", "description": "Configure pass programs for loyalty, membership, tickets, and more." }, { "name": "Pass Templates", "description": "Define pass design and field layouts." }, { "name": "Passes", "description": "Issue and manage customer passes for Apple and Google Wallet." }, { "name": "Terminals", "description": "Configure terminals for tap-to-scan functionality." }, { "name": "Transactions", "description": "Track pass usage, purchases, and redemptions." }, { "name": "Engagement", "description": "Geofences, notifications, and location-based engagement features." }, { "name": "System", "description": "Health checks and service monitoring." } ], "paths": { "/v1/passes/{passId}/transactions": { "get": { "tags": [ "Passes" ], "summary": "Get pass transactions", "description": "Retrieve transaction history for a specific pass.", "operationId": "getPassTransactions", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes/{passId}": { "get": { "tags": [ "Passes" ], "summary": "Get pass details", "description": "Retrieve details of a specific pass.", "operationId": "getPass", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "delete": { "tags": [ "Passes" ], "summary": "Void pass", "description": "Void an existing pass. This performs a soft delete by setting the pass status to VOIDED. This action cannot be undone.", "operationId": "deletePass", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "204 response", "content": {} }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "patch": { "tags": [ "Passes" ], "summary": "Update pass", "description": "Update an existing pass including customer information, status, and semantic tags. Changes propagate to the customer's mobile wallet asynchronously (eventually consistent) once the pass record is written, so a wallet may briefly still show the previous values. The response includes the permanent link field for the pass.", "operationId": "updatePass", "parameters": [ { "name": "includeWalletLink", "in": "query", "schema": { "type": "string" } }, { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePassModel" } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/templates": { "get": { "tags": [ "Pass Templates" ], "summary": "List all pass templates", "description": "Retrieve all pass templates across programs with filtering and pagination.", "operationId": "listPassTemplates", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } }, { "name": "passStyle", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassTemplateListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes/{passId}/geofences": { "get": { "tags": [ "Engagement" ], "summary": "Get pass geofences", "description": "Retrieve effective geofences for a specific pass including program-level defaults and pass-level overrides", "operationId": "getPassGeofences", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeofenceListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "put": { "tags": [ "Engagement" ], "summary": "Replace all pass geofences", "description": "Set pass-level geofence overrides that replace all program-level geofences", "operationId": "updatePassGeofences", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePassGeofencesModel" } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePassGeofencesResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "post": { "tags": [ "Engagement" ], "summary": "Add pass geofence", "description": "Add a single geofence to a pass. Maximum 10 geofences per pass.", "operationId": "addPassGeofence", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPassGeofenceModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPassGeofenceResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "delete": { "tags": [ "Engagement" ], "summary": "Delete all pass geofences", "description": "Remove all pass-level geofence overrides and revert to using program-level geofences", "operationId": "deletePassGeofences", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "204 response", "content": {} }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/programs/{programId}/encryption-key": { "get": { "tags": [ "Programs" ], "summary": "Get encryption key", "description": "Retrieve the ECDH P-256 encryption key pair for a program. Returns both compressed (Apple VAS) and uncompressed (Google Smart Tap) public key formats when available, alongside the private key needed to derive the shared secret during an NFC tap. A program has at most one key pair; a program that has never had keys generated returns 404 rather than an empty result. Treat the response as secret material: it grants the ability to decrypt that program's pass payloads.", "operationId": "getPassEncryptionKeys", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassEncryptionKeysResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/companies": { "get": { "tags": [ "Companies" ], "summary": "List companies", "description": "Returns companies accessible to your API key. Supports cursor-based pagination.", "operationId": "listCompanies", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes/{passId}/links/google": { "get": { "tags": [ "Passes" ], "summary": "Generate Google Wallet save link", "description": "Generate a time-limited URL for adding the pass to Google Wallet. The link expires after 24 hours. Deprecated: prefer the permanent link field returned on every pass object, which never expires and resolves to the applicable wallet action for any wallet type.", "operationId": "getPassGoogleWalletLink", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleWalletLinkModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ], "deprecated": true } }, "/v1/stores": { "get": { "tags": [ "Stores" ], "summary": "List stores", "description": "Returns stores for your company. Supports filtering by merchant.", "operationId": "listStores", "parameters": [ { "name": "externalId", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } }, { "name": "merchantId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "post": { "tags": [ "Stores" ], "summary": "Create store", "description": "Creates a new store for a merchant.", "operationId": "createStore", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStoreModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/programs": { "get": { "tags": [ "Programs" ], "summary": "List programs", "description": "Returns programs for your company. Supports filtering by type and status.", "operationId": "listPrograms", "parameters": [ { "name": "productType", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "merchantId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "post": { "tags": [ "Programs" ], "summary": "Create new program", "description": "Create a new loyalty or entry program. The program will be created in DRAFT status and can be published later.", "operationId": "createProgram", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProgramModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/merchants": { "get": { "tags": [ "Merchants" ], "summary": "List merchants", "description": "Returns merchants for your company. Supports filtering and pagination.", "operationId": "listMerchants", "parameters": [ { "name": "externalId", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "post": { "tags": [ "Merchants" ], "summary": "Create merchant", "description": "Creates a new merchant within your company.", "operationId": "createMerchant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes/{passId}/geofences/{geofenceId}": { "delete": { "tags": [ "Engagement" ], "summary": "Delete pass geofence by ID", "description": "Remove a specific geofence from a pass by its ID.", "operationId": "deletePassGeofence", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "geofenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "204 response", "content": {} }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "patch": { "tags": [ "Engagement" ], "summary": "Update pass geofence by ID", "description": "Update a specific geofence on a pass. Supports partial updates.", "operationId": "updatePassGeofence", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "geofenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePassGeofenceModel" } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePassGeofenceResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes/image-uploads": { "post": { "tags": [ "Passes" ], "summary": "Create pass image upload", "description": "Request an upload URL for a per-pass image override. Send the PNG or JPEG bytes to the returned URL with the declared Content-Type, then pass the uploadId as templateOverrides.images.{slot} when creating or updating a pass. You can also skip this step and pass a public HTTPS sourceUrl on the pass request directly. Unused uploads expire after 24 hours.", "operationId": "createPassImageUpload", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePassImageUploadModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassImageUploadResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/programs/{programId}": { "get": { "tags": [ "Programs" ], "summary": "Get program details", "description": "Retrieve details of a specific program", "operationId": "getProgram", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "delete": { "tags": [ "Programs" ], "summary": "Delete program", "description": "Deletes a program permanently. Fails if the program has non-voided passes.", "operationId": "deleteProgram", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "204 response", "content": {} }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "patch": { "tags": [ "Programs" ], "summary": "Update program", "description": "Update an existing program. Supports partial updates.", "operationId": "updateProgram", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProgramModel" } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes": { "get": { "tags": [ "Passes" ], "summary": "List passes", "description": "Returns passes for your company. Supports filtering, sorting, and pagination.", "operationId": "listPasses", "parameters": [ { "name": "phoneNumber", "in": "query", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } }, { "name": "externalId", "in": "query", "schema": { "type": "string" } }, { "name": "programId", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "walletType", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "post": { "tags": [ "Passes" ], "summary": "Create new pass", "description": "Create a new pass for a program. The pass is created in PREACTIVE status and includes a unique authentication token. The response includes the permanent link field for the pass.", "operationId": "createPass", "parameters": [ { "name": "includeWalletLink", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePassModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/companies/{companyId}": { "get": { "tags": [ "Companies" ], "summary": "Get company details", "description": "Returns details for a specific company.", "operationId": "getCompany", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/programs/{programId}/templates/{templateId}": { "get": { "tags": [ "Pass Templates" ], "summary": "Get program pass template", "description": "Retrieve complete details about a specific template within a program.", "operationId": "getProgramPassTemplate", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassTemplateResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "delete": { "tags": [ "Pass Templates" ], "summary": "Delete program pass template", "description": "Permanently deletes a pass template from a program. Fails if the program has non-voided passes.", "operationId": "deleteProgramPassTemplate", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "204 response", "content": {} }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "patch": { "tags": [ "Pass Templates" ], "summary": "Update program pass template", "description": "Update design configuration or settings for an existing template within a program.", "operationId": "updateProgramPassTemplate", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePassTemplateModel" } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassTemplateResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes/{passId}/links/apple": { "get": { "tags": [ "Passes" ], "summary": "Generate Apple Wallet installation link", "description": "Generate a time-limited URL for adding the pass to Apple Wallet. Deprecated: prefer the permanent link field returned on every pass object, which never expires and resolves to the applicable wallet action for any wallet type.", "operationId": "getPassAppleWalletLink", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppleWalletLinkModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ], "deprecated": true } }, "/v1/terminals/{terminalId}": { "get": { "tags": [ "Terminals" ], "summary": "Get terminal details", "description": "Retrieve details of a specific terminal.", "operationId": "getTerminal", "parameters": [ { "name": "terminalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "delete": { "tags": [ "Terminals" ], "summary": "Delete terminal", "description": "Deletes a terminal permanently.", "operationId": "deleteTerminal", "parameters": [ { "name": "terminalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "204 response", "content": {} }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "patch": { "tags": [ "Terminals" ], "summary": "Update terminal", "description": "Update terminal information. Supports partial updates.", "operationId": "updateTerminal", "parameters": [ { "name": "terminalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTerminalModel" } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/stores/{storeId}": { "get": { "tags": [ "Stores" ], "summary": "Get store details", "description": "Returns details for a specific store.", "operationId": "getStore", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "delete": { "tags": [ "Stores" ], "summary": "Delete store", "description": "Deletes a store permanently. Fails if store has existing terminals or transactions.", "operationId": "deleteStore", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "204 response", "content": {} }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "patch": { "tags": [ "Stores" ], "summary": "Update store", "description": "Update store information. Supports partial updates.", "operationId": "updateStore", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStoreModel" } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/terminals": { "get": { "tags": [ "Terminals" ], "summary": "List terminals", "description": "List all terminals with optional filters.", "operationId": "listTerminals", "parameters": [ { "name": "storeId", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "post": { "tags": [ "Terminals" ], "summary": "Create terminal", "description": "Create a new terminal at a store.", "operationId": "createTerminal", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTerminalModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/templates/{templateId}": { "get": { "tags": [ "Pass Templates" ], "summary": "Get pass template details", "description": "Retrieve complete details about a specific pass template.", "operationId": "getPassTemplate", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassTemplateResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/merchants/{merchantId}": { "get": { "tags": [ "Merchants" ], "summary": "Get merchant details", "description": "Returns details for a specific merchant.", "operationId": "getMerchant", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "delete": { "tags": [ "Merchants" ], "summary": "Delete merchant", "description": "Deletes a merchant permanently. Fails if merchant has existing stores.", "operationId": "deleteMerchant", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "204 response", "content": {} }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "patch": { "tags": [ "Merchants" ], "summary": "Update merchant", "description": "Updates an existing merchant. Only provided fields will be modified.", "operationId": "updateMerchant", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantModel" } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/apple/passes/secure": { "post": { "tags": [ "Passes" ], "summary": "Create secure Apple Wallet pass", "description": "Create a secure Apple Wallet pass with account binding and enhanced security.", "operationId": "createSecurePass", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecurePassModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurePassResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/programs/{programId}/templates": { "get": { "tags": [ "Pass Templates" ], "summary": "List program pass templates", "description": "Retrieve all pass templates for a specific program.", "operationId": "listProgramPassTemplates", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassTemplateListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "post": { "tags": [ "Pass Templates" ], "summary": "Create program pass template", "description": "Create a new pass template within a program. Each program supports at most one template.", "operationId": "createProgramPassTemplate", "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePassTemplateModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassTemplateResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes/{passId}/registrations": { "get": { "tags": [ "Passes" ], "summary": "Get pass registrations", "description": "Retrieve Apple Wallet device registrations for a specific pass.", "operationId": "getPassRegistrations", "parameters": [ { "name": "passId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/transactions/{transactionId}": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction details", "description": "Retrieve details of a specific transaction.", "operationId": "getTransaction", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/health": { "get": { "tags": [ "System" ], "summary": "Health check", "description": "Returns service status, version, and environment details. Does not require authentication.", "operationId": "healthCheck", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthModel" } } } }, "503": { "description": "503 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthModel" } } } } } } }, "/v1/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions", "description": "List all transactions with optional filters.", "operationId": "listTransactions", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] }, "post": { "tags": [ "Transactions" ], "summary": "Create transaction", "description": "Record a new transaction against a pass.", "operationId": "createTransaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } }, "/v1/passes/batch": { "post": { "tags": [ "Passes" ], "summary": "Batch create passes", "description": "Create multiple passes in a single request. Supports up to 1000 passes per call with automatic duplicate detection.", "operationId": "batchCreatePasses", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreatePassesModel" } } }, "required": true }, "responses": { "201": { "description": "201 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreatePassesResponseModel" } } } }, "400": { "description": "400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400Model" } } } }, "401": { "description": "401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401Model" } } } }, "403": { "description": "403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403Model" } } } }, "404": { "description": "404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Model" } } } }, "500": { "description": "500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500Model" } } } } }, "security": [ { "StellApiAuthorizer": [] } ] } } }, "components": { "schemas": { "SecurePassResponseModel": { "title": "SecurePassResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "pass", "secureUrl" ], "type": "object", "properties": { "secureUrl": { "type": "string", "description": "Secure access URL cryptographically bound to the requesting device", "format": "uri" }, "pass": { "required": [ "createdAt", "id", "programId", "status", "updatedAt" ], "type": "object", "properties": { "createdAt": { "type": "string", "description": "When the pass was created", "format": "date-time" }, "link": { "type": "string", "description": "Permanent public link for the pass. Never expires; resolves at open time to the applicable wallet action. Append ?delivery=direct to 302 straight to the wallet artifact instead of the landing page.", "format": "uri" }, "externalId": { "type": "string", "description": "External reference ID" }, "maxDistance": { "minimum": 1, "type": "integer", "description": "Maximum distance in meters for location relevance" }, "id": { "type": "string", "description": "Unique pass identifier" }, "membershipStatus": { "maxLength": 255, "type": "string", "description": "Merchant-defined membership status (max 255 characters)" }, "programId": { "type": "string", "description": "Parent program ID" }, "status": { "type": "string", "description": "Current pass status" }, "customer": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Customer first name" }, "lastName": { "type": "string", "description": "Customer last name" }, "emailAddress": { "type": "string", "description": "Customer email address" }, "personalId": { "maxLength": 64, "type": "string", "description": "National/personal identity number (e.g., Swedish personnummer). Optional. PII — sent only when required by merchant." }, "lookupSource": { "maxLength": 50, "type": "string", "description": "Which CRM was queried for new/existing determination" }, "phone": { "type": "string", "description": "Customer phone number (deprecated - use mobileNumber)" }, "mobileNumber": { "type": "string", "description": "Customer mobile phone number" }, "isNew": { "type": "boolean", "description": "Whether the customer was new (not found in merchant CRM) at pass creation time" }, "email": { "type": "string", "description": "Customer email address (deprecated - use emailAddress)" } }, "description": "Customer information" }, "updatedAt": { "type": "string", "description": "When the pass was last updated", "format": "date-time" } }, "description": "The created account-bound pass" } }, "description": "Created pass and its secure access URL" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Apple secure pass creation response." }, "CreateStoreModel": { "title": "Create Store Request", "required": [ "merchantId", "name" ], "type": "object", "properties": { "merchantId": { "type": "string", "description": "ID of the merchant this store belongs to" }, "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Store name" }, "externalId": { "minLength": 1, "type": "string", "description": "External system identifier for integration" }, "location": { "type": "object", "properties": { "phoneNumber": { "maxLength": 50, "type": "string", "description": "Public phone number for this location" }, "address": { "type": "object", "properties": { "country": { "maxLength": 2, "type": "string", "description": "Two-letter ISO 3166-1 country code, such as \"NO\" or \"DK\"" }, "city": { "maxLength": 100, "type": "string", "description": "City" }, "street": { "maxLength": 200, "type": "string", "description": "Street name and number" }, "postalCode": { "maxLength": 20, "type": "string", "description": "Postal or ZIP code" }, "state": { "maxLength": 100, "type": "string", "description": "State, province or region" } }, "additionalProperties": false, "description": "Street address of the store" }, "coordinate": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "Geographic coordinate of the store." }, "name": { "maxLength": 200, "type": "string", "description": "Name for this location, if it differs from the store name" }, "description": { "maxLength": 500, "type": "string", "description": "Free-text note about the location, such as \"Second floor, next to the elevators\"" } }, "additionalProperties": false, "description": "Physical location of the store: address, coordinate and contact details." } }, "additionalProperties": false }, "PassTemplateResponseModel": { "title": "PassTemplateResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PassTemplateModel" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response envelope carrying a pass template." }, "RegistrationListModel": { "title": "RegistrationListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "registrations" ], "type": "object", "properties": { "registrations": { "type": "array", "description": "The registrations in this page of results", "items": { "required": [ "deviceLibraryIdentifier", "id", "passId", "passTypeIdentifier" ], "type": "object", "properties": { "deviceLibraryIdentifier": { "type": "string", "description": "Unique identifier for the Apple device" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when device was registered", "format": "date-time" }, "passId": { "type": "string", "description": "ID of the pass registered to this device" }, "id": { "type": "string", "description": "Unique registration identifier" }, "passTypeIdentifier": { "type": "string", "description": "Apple Pass Type ID (e.g., pass.com.company.loyalty)" }, "pushToken": { "type": "string", "description": "Apple Push Notification token for sending updates" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when registration was last updated", "format": "date-time" } } } }, "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" } }, "description": "Page of registrations plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "TerminalResponseModel": { "title": "TerminalResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TerminalModel" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response envelope carrying a terminal." }, "ProgramModel": { "title": "ProgramModel", "required": [ "companyId", "createdAt", "id", "name", "status", "type", "updatedAt" ], "type": "object", "properties": { "country": { "pattern": "^[A-Z]{2}$", "type": "string", "description": "ISO 3166-1 alpha-2 country code for the program operating country" }, "displayName": { "type": "string", "description": "Public-facing program name shown to customers" }, "description": { "type": "string", "description": "Detailed description of the program and its benefits" }, "type": { "type": "string", "description": "Pass type determining wallet style and functionality", "enum": [ "LOYALTY_CARD", "STAMP_CARD", "ID_CARD", "BOARDING_PASS", "EVENT_TICKET", "COUPON", "STORE_CARD", "GIFT_CARD", "GENERIC_CARD" ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the program was created", "format": "date-time" }, "companyId": { "type": "string", "description": "ID of the company that owns this program" }, "merchantId": { "type": "string", "description": "ID of the merchant this program is associated with (optional for company-wide programs)" }, "name": { "type": "string", "description": "Internal program name used for administration" }, "id": { "type": "string", "description": "Unique program identifier in ULID format" }, "passTypeIdentifier": { "type": "string", "description": "Apple Wallet pass type identifier" }, "productType": { "type": "string", "description": "Product tier determining available features", "enum": [ "ENTRY", "LOYALTY" ] }, "status": { "type": "string", "description": "Current lifecycle status of the program", "enum": [ "DRAFT", "PUBLISHED", "DELETED", "ARCHIVED" ] }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the program was last updated", "format": "date-time" } }, "description": "Pass program configuration." }, "MerchantModel": { "title": "MerchantModel", "required": [ "companyId", "createdAt", "id", "name", "status", "updatedAt" ], "type": "object", "properties": { "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the merchant was created", "format": "date-time" }, "companyId": { "type": "string", "description": "ID of the parent company this merchant belongs to" }, "name": { "type": "string", "description": "Merchant business name" }, "externalId": { "type": "string", "description": "External system identifier for integration purposes" }, "location": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "Contact phone number" }, "address": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "city": { "type": "string", "description": "City name" }, "street": { "type": "string", "description": "Street address" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "state": { "type": "string", "description": "State or province code" } }, "description": "Physical address details" }, "coordinate": { "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters" }, "latitude": { "type": "number", "description": "Geographic latitude coordinate" }, "longitude": { "type": "number", "description": "Geographic longitude coordinate" } }, "description": "Geographic coordinates" }, "name": { "type": "string", "description": "Location name or label" }, "description": { "type": "string", "description": "Location description or additional details" } }, "description": "Physical location details for the merchant" }, "id": { "type": "string", "description": "Unique merchant identifier in ULID format" }, "status": { "type": "string", "description": "Current operational status of the merchant", "enum": [ "PREACTIVE", "ACTIVE", "INACTIVE", "CLOSED" ] }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the merchant was last updated", "format": "date-time" } }, "description": "Brand or business unit within a company." }, "PassListModel": { "title": "PassListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "passes" ], "type": "object", "properties": { "passes": { "type": "array", "description": "The passes in this page of results", "items": { "required": [ "createdAt", "id", "programId", "status", "updatedAt" ], "type": "object", "properties": { "externalReference": { "type": "string", "description": "Additional external reference for integration with external systems" }, "createdAt": { "type": "string", "description": "When the pass was created", "format": "date-time" }, "walletType": { "type": "string", "description": "Wallet platform where the pass is installed", "enum": [ "APPLE_WALLET", "GOOGLE_WALLET", "UNKNOWN" ] }, "link": { "type": "string", "description": "Permanent public link for the pass. Never expires, safe to print and email; resolves at open time to the applicable wallet action. Append ?delivery=direct to 302 straight to the wallet artifact (the .pkpass file for Apple Wallet, the save link for Google Wallet) instead of the landing page.", "format": "uri" }, "externalId": { "type": "string", "description": "External reference ID" }, "id": { "type": "string", "description": "Unique pass identifier" }, "programId": { "type": "string", "description": "Parent program ID" }, "status": { "type": "string", "description": "Pass status", "enum": [ "PREACTIVE", "ACTIVE", "INACTIVE", "VOIDED", "REVOKED", "EXPIRED" ] }, "customer": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Customer first name" }, "lastName": { "type": "string", "description": "Customer last name" }, "emailAddress": { "type": "string", "description": "Customer email address", "format": "email" }, "personalId": { "maxLength": 64, "type": "string", "description": "National/personal identity number (e.g., Swedish personnummer). Optional. PII — sent only when required by merchant." }, "lookupSource": { "maxLength": 50, "type": "string", "description": "Which CRM was queried for new/existing determination (e.g., \"voyado\", \"bloomreach\")" }, "phone": { "type": "string", "description": "Customer phone number (deprecated - use mobileNumber)" }, "mobileNumber": { "type": "string", "description": "Customer mobile phone number" }, "isNew": { "type": "boolean", "description": "Whether the customer was new (not found in merchant CRM) at pass creation time" }, "email": { "type": "string", "description": "Customer email address (deprecated - use emailAddress)", "format": "email" } }, "additionalProperties": false, "description": "Customer information" }, "updatedAt": { "type": "string", "description": "When the pass was last updated", "format": "date-time" } } } }, "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" } }, "description": "Page of passes plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "CompanyResponseModel": { "title": "CompanyResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyModel" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response envelope carrying a company." }, "CreateTerminalModel": { "title": "CreateTerminalModel", "required": [ "storeId" ], "type": "object", "properties": { "note": { "maxLength": 1000, "type": "string", "description": "Additional notes about the terminal" }, "serialNumber": { "maxLength": 100, "type": "string", "description": "Hardware serial number" }, "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Terminal display name" }, "externalId": { "maxLength": 255, "type": "string", "description": "External reference ID" }, "storeId": { "type": "string", "description": "ID of the store this terminal belongs to" }, "status": { "type": "string", "description": "Terminal operational status. Defaults to ACTIVE.", "enum": [ "ONLINE", "OFFLINE", "SWITCHED_OFF", "MAINTENANCE", "ERROR" ] } }, "description": "Data required to register a new terminal." }, "TransactionModel": { "title": "TransactionModel", "required": [ "createdAt", "id", "passId", "transactionDate", "type", "updatedAt" ], "type": "object", "properties": { "tapMode": { "type": "string", "description": "Whether pass and payment were captured in one terminal tap (SINGLE_TAP), separate taps (DOUBLE_TAP), or without a terminal (NONE)", "enum": [ "SINGLE_TAP", "DOUBLE_TAP", "NONE" ] }, "pointsSpent": { "type": "number", "description": "Loyalty points redeemed in this transaction" }, "passId": { "type": "string", "description": "ID of the pass associated with this transaction" }, "channel": { "type": "string", "description": "Where the customer was: IN_STORE or ONLINE", "enum": [ "IN_STORE", "ONLINE" ] }, "instrument": { "type": "string", "description": "How the pass was presented. CARD, CASH and MOBILE only appear on transactions recorded before payment.method existed.", "enum": [ "APPLE_VAS", "GOOGLE_SMART_TAP", "QR", "NFC_TYPE_1", "NFC_TYPE_2", "NFC_TYPE_3", "NFC_TYPE_4", "NFC_TYPE_5", "MIFARE", "OTHER", "CARD", "CASH", "MOBILE" ] }, "remainingUsesBefore": { "type": "integer", "description": "Number of remaining uses before this transaction (for access control)" }, "terminalId": { "type": "string", "description": "ID of the terminal that processed the transaction" }, "storeId": { "type": "string", "description": "ID of the store where transaction occurred" }, "type": { "type": "string", "description": "What happened to the pass. ONLINE, PASS_AND_PAYMENT, PASS_ONLY and PAYMENT_ONLY only appear on transactions recorded before channel and tapMode existed.", "enum": [ "PURCHASE", "REDEMPTION", "POINTS_ADJUSTMENT", "SCAN_ONLY", "CHECK_IN", "CHECK_OUT", "UNKNOWN", "ONLINE", "PASS_AND_PAYMENT", "PASS_ONLY", "PAYMENT_ONLY" ] }, "transactionDate": { "type": "string", "description": "When the transaction occurred", "format": "date-time" }, "reference": { "type": "string", "description": "External transaction reference" }, "createdAt": { "type": "string", "description": "When the transaction was created", "format": "date-time" }, "pointsEarned": { "type": "number", "description": "Loyalty points earned in this transaction" }, "statusReason": { "type": "string", "description": "Reason for transaction status (e.g., denial reason)" }, "remainingUsesAfter": { "type": "integer", "description": "Number of remaining uses after this transaction (for access control)" }, "payment": { "type": "object", "properties": { "reference": { "type": "string", "description": "Payment reference identifier" }, "amount": { "type": "object", "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "ISO 4217 currency code" }, "value": { "minimum": 0, "type": "number", "description": "Payment amount value" } }, "additionalProperties": false, "description": "Payment amount details" }, "method": { "type": "string", "description": "How the customer paid", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "CARD", "CASH", "VIPPS", "MOBILEPAY", "OTHER" ] }, "pspReference": { "type": "string", "description": "Payment service provider reference" } }, "additionalProperties": false, "description": "Payment details" }, "id": { "type": "string", "description": "Unique transaction identifier" }, "additionalData": { "type": "object", "additionalProperties": true, "description": "Custom transaction data" }, "status": { "type": "string", "description": "Transaction status", "enum": [ "APPROVED", "DENIED", "FAILED", "PENDING" ] }, "updatedAt": { "type": "string", "description": "When the transaction was last updated", "format": "date-time" } }, "description": "Record of a pass scan, purchase, or redemption." }, "TerminalModel": { "title": "TerminalModel", "required": [ "createdAt", "id", "storeId", "updatedAt" ], "type": "object", "properties": { "note": { "maxLength": 1000, "type": "string", "description": "Additional notes about the terminal" }, "createdAt": { "type": "string", "description": "When the terminal was created", "format": "date-time" }, "serialNumber": { "maxLength": 100, "type": "string", "description": "Hardware serial number" }, "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Terminal display name" }, "externalId": { "maxLength": 255, "type": "string", "description": "External reference ID" }, "id": { "type": "string", "description": "Unique terminal identifier" }, "storeId": { "type": "string", "description": "ID of the store this terminal belongs to" }, "status": { "type": "string", "description": "Terminal operational status", "enum": [ "ONLINE", "OFFLINE", "SWITCHED_OFF", "MAINTENANCE", "ERROR" ] }, "updatedAt": { "type": "string", "description": "When the terminal was last updated", "format": "date-time" } }, "description": "Terminal for tap-to-scan pass validation." }, "TransactionListModel": { "title": "TransactionListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "transactions" ], "type": "object", "properties": { "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" }, "transactions": { "type": "array", "description": "The transactions in this page of results", "items": { "required": [ "createdAt", "id", "passId", "transactionDate", "type", "updatedAt" ], "type": "object", "properties": { "tapMode": { "type": "string", "description": "Whether pass and payment were captured in one terminal tap (SINGLE_TAP), separate taps (DOUBLE_TAP), or without a terminal (NONE)", "enum": [ "SINGLE_TAP", "DOUBLE_TAP", "NONE" ] }, "pointsSpent": { "type": "number", "description": "Loyalty points redeemed" }, "passId": { "type": "string", "description": "Associated pass ID" }, "channel": { "type": "string", "description": "Where the customer was: IN_STORE or ONLINE", "enum": [ "IN_STORE", "ONLINE" ] }, "instrument": { "type": "string", "description": "How the pass was presented. CARD, CASH and MOBILE only appear on transactions recorded before payment.method existed.", "enum": [ "APPLE_VAS", "GOOGLE_SMART_TAP", "QR", "NFC_TYPE_1", "NFC_TYPE_2", "NFC_TYPE_3", "NFC_TYPE_4", "NFC_TYPE_5", "MIFARE", "OTHER", "CARD", "CASH", "MOBILE" ] }, "remainingUsesBefore": { "type": "integer", "description": "Remaining uses on the pass before this transaction was applied" }, "terminalId": { "type": "string", "description": "Terminal ID that processed transaction" }, "storeId": { "type": "string", "description": "Store ID where transaction occurred" }, "type": { "type": "string", "description": "What happened to the pass. ONLINE, PASS_AND_PAYMENT, PASS_ONLY and PAYMENT_ONLY only appear on transactions recorded before channel and tapMode existed.", "enum": [ "PURCHASE", "REDEMPTION", "POINTS_ADJUSTMENT", "SCAN_ONLY", "CHECK_IN", "CHECK_OUT", "UNKNOWN", "ONLINE", "PASS_AND_PAYMENT", "PASS_ONLY", "PAYMENT_ONLY" ] }, "transactionDate": { "type": "string", "description": "When the transaction occurred", "format": "date-time" }, "reference": { "type": "string", "description": "External transaction reference" }, "createdAt": { "type": "string", "description": "When the transaction was created", "format": "date-time" }, "pointsEarned": { "type": "number", "description": "Loyalty points earned" }, "statusReason": { "type": "string", "description": "Human-readable reason for the status, present when denied or failed" }, "remainingUsesAfter": { "type": "integer", "description": "Remaining uses on the pass after this transaction was applied" }, "payment": { "type": "object", "properties": { "reference": { "type": "string", "description": "Payment reference identifier" }, "amount": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code" }, "value": { "type": "number", "description": "Payment amount value" } }, "description": "Payment amount details" }, "method": { "type": "string", "description": "How the customer paid", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "CARD", "CASH", "VIPPS", "MOBILEPAY", "OTHER" ] }, "pspReference": { "type": "string", "description": "Payment service provider reference" } }, "description": "Payment details, present when the transaction involved a payment" }, "id": { "type": "string", "description": "Unique transaction identifier" }, "additionalData": { "type": "object", "additionalProperties": true, "description": "Merchant-defined metadata attached to the transaction" }, "status": { "type": "string", "description": "Outcome of the transaction", "enum": [ "APPROVED", "DENIED", "FAILED", "PENDING" ] }, "updatedAt": { "type": "string", "description": "When the transaction was last updated", "format": "date-time" } } } } }, "description": "Page of transactions plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "MerchantListModel": { "title": "MerchantListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "merchants" ], "type": "object", "properties": { "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" }, "merchants": { "type": "array", "description": "The merchants in this page of results", "items": { "required": [ "companyId", "createdAt", "id", "name", "status", "updatedAt" ], "type": "object", "properties": { "createdAt": { "type": "string", "description": "When the merchant was created", "format": "date-time" }, "companyId": { "type": "string", "description": "Parent company ID" }, "name": { "type": "string", "description": "Merchant business name" }, "externalId": { "type": "string", "description": "External system identifier" }, "location": { "type": "object", "properties": { "country": { "type": "string", "description": "Country code" }, "address": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City name" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "latitude": { "type": "number", "description": "Latitude coordinate" }, "state": { "type": "string", "description": "State or province" }, "longitude": { "type": "number", "description": "Longitude coordinate" } }, "description": "Merchant's physical address and coordinates" }, "id": { "type": "string", "description": "Unique merchant identifier" }, "status": { "type": "string", "description": "Current operational status", "enum": [ "PREACTIVE", "ACTIVE", "INACTIVE", "CLOSED" ] }, "updatedAt": { "type": "string", "description": "When the merchant was last updated", "format": "date-time" } } } } }, "description": "Page of merchants plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "Error404Model": { "title": "Error404Model", "required": [ "error", "requestId" ], "type": "object", "properties": { "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" }, "error": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "NOT_FOUND" ] }, "details": { "type": "object", "additionalProperties": true, "description": "Additional error context" }, "message": { "type": "string", "description": "Human-readable error message", "default": "Resource not found" } }, "description": "Error information" } }, "description": "Resource not found." }, "CompanyListModel": { "title": "CompanyListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "companies" ], "type": "object", "properties": { "companies": { "type": "array", "description": "The companies in this page of results", "items": { "required": [ "createdAt", "id", "name", "status", "updatedAt" ], "type": "object", "properties": { "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the company was created", "format": "date-time" }, "name": { "type": "string", "description": "Company name displayed in the system" }, "externalId": { "type": "string", "description": "External reference ID for integration with third-party systems" }, "id": { "type": "string", "description": "Unique company identifier in ULID format" }, "status": { "type": "string", "description": "Current operational status of the company", "enum": [ "PREACTIVE", "ACTIVE", "INACTIVE", "CLOSED" ] }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the company was last updated", "format": "date-time" } } } }, "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" } }, "description": "Page of companies plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "ProgramListModel": { "title": "ProgramListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "programs" ], "type": "object", "properties": { "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" }, "programs": { "type": "array", "description": "The programs in this page of results", "items": { "required": [ "companyId", "createdAt", "id", "name", "status", "type", "updatedAt" ], "type": "object", "properties": { "createdAt": { "type": "string", "description": "When the program was created", "format": "date-time" }, "companyId": { "type": "string", "description": "Parent company ID" }, "merchantId": { "type": "string", "description": "Associated merchant ID (optional)" }, "displayName": { "type": "string", "description": "Public-facing program name" }, "name": { "type": "string", "description": "Internal program name" }, "description": { "type": "string", "description": "Program description" }, "id": { "type": "string", "description": "Unique program identifier" }, "type": { "type": "string", "description": "Pass type this program issues", "enum": [ "LOYALTY_CARD", "STAMP_CARD", "ID_CARD", "BOARDING_PASS", "EVENT_TICKET", "COUPON", "STORE_CARD", "GIFT_CARD", "GENERIC_CARD" ] }, "productType": { "type": "string", "description": "Product tier", "enum": [ "ENTRY", "LOYALTY" ] }, "status": { "type": "string", "description": "Program status", "enum": [ "DRAFT", "PUBLISHED", "DELETED", "ARCHIVED" ] }, "updatedAt": { "type": "string", "description": "When the program was last updated", "format": "date-time" } } } } }, "description": "Page of programs plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "CreateSecurePassModel": { "title": "CreateSecurePassModel", "required": [ "programId" ], "type": "object", "properties": { "templateOverrides": { "$ref": "#/components/schemas/TemplateOverridesModel" }, "payload": { "type": "string", "description": "NFC or QR payload (defaults to pass ID if not provided)" }, "attribution": { "type": "object", "properties": { "referrerHost": { "maxLength": 253, "type": "string", "description": "Referrer host only, never a full URL" }, "reference": { "maxLength": 200, "type": "string", "description": "Opaque correlation id: request id, endpoint id, session id" }, "origin": { "type": "string", "description": "STELL = a Stell-hosted surface, MERCHANT = the merchant's own code calling the API (default), PARTNER = a third-party connector acting for the merchant", "enum": [ "STELL", "MERCHANT", "PARTNER" ] }, "channel": { "type": "string", "description": "Where the person came from. When omitted it is DECLARED from campaign.medium (email, sms, qr, print, terminal, social, paid, web) or otherwise INFERRED from the mechanism.", "enum": [ "EMAIL", "SMS", "QR", "PRINT", "TERMINAL", "SOCIAL", "PAID", "WEB", "DIRECT", "UNKNOWN" ] }, "campaign": { "type": "object", "properties": { "campaign": { "maxLength": 200, "type": "string" }, "term": { "maxLength": 200, "type": "string" }, "source": { "maxLength": 200, "type": "string" }, "medium": { "maxLength": 200, "type": "string" }, "content": { "maxLength": 200, "type": "string" } }, "additionalProperties": false, "description": "utm_* parameters as received" }, "mechanism": { "type": "string", "description": "How the pass was created. Named for what happened, never for which system did it.", "enum": [ "API", "VAS_PERSONALIZATION", "VAS_MEMBER_LINK", "ADMIN_FORM", "PORTAL_ISSUE", "ONBOARDING_FORM", "ONBOARDING_FORM_OTP", "ONBOARDING_FORM_IDENTITY", "PREBOARDING_LINK", "DIRECT_LINK", "EMBED_WIDGET", "APP_CLIP", "CRM_SYNC" ] }, "channelConfidence": { "type": "string", "description": "DECLARED when the channel came from utm_medium or the caller, INFERRED otherwise", "enum": [ "DECLARED", "INFERRED" ] }, "landingPath": { "maxLength": 200, "type": "string", "description": "Landing route template (e.g. /p/{nanoId}/{memberId}), never a real id" }, "identityProvider": { "pattern": "^[a-z0-9-]{1,50}$", "type": "string", "description": "Identity provider slug (e.g. vipps) the person authenticated with. Required with mechanism ONBOARDING_FORM_IDENTITY and rejected with 400 on any other mechanism." } }, "additionalProperties": false, "description": "Attribution: whose surface created the pass (origin), how it was created (mechanism) and where the person came from (channel + campaign). Every field is optional; absent fields default to origin MERCHANT, mechanism API, channel inferred, reference = request id." }, "externalId": { "type": "string", "description": "External reference ID" }, "semanticTagOverrides": { "$ref": "#/components/schemas/SemanticTagsModel" }, "membershipStatus": { "maxLength": 255, "type": "string", "description": "Merchant-defined account status (e.g., \"Active\", \"Suspended\", \"On Hold\")" }, "programId": { "minLength": 1, "type": "string", "description": "ID of the program to create pass for" }, "customer": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Customer first name" }, "lastName": { "type": "string", "description": "Customer last name" }, "emailAddress": { "type": "string", "description": "Customer email address for notifications", "format": "email" }, "personalId": { "maxLength": 64, "type": "string", "description": "National/personal identity number (e.g., Swedish personnummer). Optional. PII — sent only when required by merchant." }, "lookupSource": { "maxLength": 50, "pattern": "^[a-z0-9-]+$", "type": "string", "description": "Which CRM was queried for new/existing determination (e.g., \"voyado\")" }, "phone": { "type": "string", "description": "Customer phone number (deprecated - use mobileNumber)" }, "mobileNumber": { "type": "string", "description": "Customer mobile phone number for SMS delivery" }, "isNew": { "type": "boolean", "description": "Whether the customer is new (not found in merchant CRM). Set at creation, immutable." }, "email": { "type": "string", "description": "Customer email address (deprecated - use emailAddress)", "format": "email" } }, "description": "Customer information" } }, "description": "Data for Apple secure pass with account binding." }, "AppleWalletLinkModel": { "title": "AppleWalletLinkModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "downloadUrl", "expiresAt", "passId" ], "type": "object", "properties": { "passId": { "type": "string", "description": "Unique identifier for the pass" }, "downloadUrl": { "type": "string", "description": "Temporary download URL for the .pkpass file", "format": "uri" }, "expiresAt": { "type": "string", "description": "Link expiration timestamp", "format": "date-time" } }, "additionalProperties": false, "description": "Apple Wallet link data" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "additionalProperties": false, "description": "Apple Wallet installation link." }, "CreateProgramModel": { "title": "CreateProgramModel", "required": [ "name", "type" ], "type": "object", "properties": { "country": { "pattern": "^[A-Z]{2}$", "type": "string", "description": "ISO 3166-1 alpha-2 country code for the program operating country" }, "merchantId": { "type": "string", "description": "ID of the merchant to associate the program with (optional for company-wide programs)" }, "displayName": { "maxLength": 100, "type": "string", "description": "Public-facing program name (max 100 characters)" }, "name": { "maxLength": 100, "minLength": 2, "type": "string", "description": "Internal program name (2-100 characters)" }, "description": { "maxLength": 500, "type": "string", "description": "Program description shown to customers (max 500 characters)" }, "type": { "type": "string", "description": "Pass type determining wallet style and functionality", "enum": [ "LOYALTY_CARD", "STAMP_CARD", "ID_CARD", "BOARDING_PASS", "EVENT_TICKET", "COUPON", "STORE_CARD", "GIFT_CARD", "GENERIC_CARD" ] }, "productType": { "type": "string", "description": "Product tier (ENTRY: basic features, LOYALTY: advanced features)", "enum": [ "ENTRY", "LOYALTY" ] } }, "description": "Data required to create a new program." }, "Error500Model": { "title": "Error500Model", "required": [ "error", "requestId" ], "type": "object", "properties": { "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" }, "error": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "INTERNAL_ERROR" ] }, "details": { "type": "object", "additionalProperties": true, "description": "Additional error context" }, "message": { "type": "string", "description": "Human-readable error message", "default": "An internal server error occurred" } }, "description": "Error information" } }, "description": "Internal server error." }, "MerchantResponseModel": { "title": "MerchantResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MerchantModel" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response envelope carrying a merchant." }, "UpdateStoreModel": { "title": "UpdateStoreModel", "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Store name" }, "externalId": { "minLength": 1, "type": "string", "description": "Update external system identifier" }, "location": { "type": "object", "properties": { "phoneNumber": { "maxLength": 50, "type": "string", "description": "Public phone number for this location" }, "address": { "type": "object", "properties": { "country": { "maxLength": 2, "type": "string", "description": "Two-letter ISO 3166-1 country code, such as \"NO\" or \"DK\"" }, "city": { "maxLength": 100, "type": "string", "description": "City" }, "street": { "maxLength": 200, "type": "string", "description": "Street name and number" }, "postalCode": { "maxLength": 20, "type": "string", "description": "Postal or ZIP code" }, "state": { "maxLength": 100, "type": "string", "description": "State, province or region" } }, "additionalProperties": false, "description": "Street address of the store" }, "coordinate": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "Geographic coordinate of the store." }, "name": { "maxLength": 200, "type": "string", "description": "Name for this location, if it differs from the store name" }, "description": { "maxLength": 500, "type": "string", "description": "Free-text note about the location, such as \"Second floor, next to the elevators\"" } }, "additionalProperties": false, "description": "Physical location of the store: address, coordinate and contact details." } }, "additionalProperties": false, "description": "Fields to update on an existing store." }, "PassResponseModel": { "title": "PassResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PassModel" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response envelope carrying a pass." }, "StoreModel": { "title": "StoreModel", "required": [ "createdAt", "id", "merchantId", "name", "updatedAt" ], "type": "object", "properties": { "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the store was created", "format": "date-time" }, "merchantId": { "type": "string", "description": "ID of the merchant this store belongs to" }, "name": { "type": "string", "description": "Store name or location identifier" }, "externalId": { "type": "string", "description": "External system identifier for integration purposes" }, "location": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "Contact phone number" }, "address": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "city": { "type": "string", "description": "City name" }, "street": { "type": "string", "description": "Street address" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "state": { "type": "string", "description": "State or province code" } }, "description": "Physical address details" }, "coordinate": { "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters" }, "latitude": { "type": "number", "description": "Geographic latitude coordinate" }, "longitude": { "type": "number", "description": "Geographic longitude coordinate" } }, "description": "Geographic coordinates for location-based services" }, "name": { "type": "string", "description": "Location name or label" }, "description": { "type": "string", "description": "Location description or additional details" } }, "description": "Physical location details for the store" }, "id": { "type": "string", "description": "Unique store identifier in ULID format" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the store was last updated", "format": "date-time" } }, "description": "Physical or virtual location where customers interact." }, "UpdateProgramModel": { "title": "UpdateProgramModel", "type": "object", "properties": { "country": { "pattern": "^[A-Z]{2}$", "type": "string", "description": "ISO 3166-1 alpha-2 country code for the program operating country" }, "merchantId": { "type": "string", "description": "Update merchant association (can be set or cleared)" }, "displayName": { "maxLength": 100, "type": "string", "description": "Public-facing program name (max 100 characters)" }, "name": { "maxLength": 100, "minLength": 2, "type": "string", "description": "Internal program name (2-100 characters)" }, "description": { "maxLength": 500, "type": "string", "description": "Program description shown to customers (max 500 characters)" }, "status": { "type": "string", "description": "Update program lifecycle status", "enum": [ "DRAFT", "PUBLISHED", "DELETED", "ARCHIVED" ] } }, "description": "Fields to update on an existing program." }, "TransactionResponseModel": { "title": "TransactionResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TransactionModel" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response envelope carrying a transaction." }, "PassModel": { "title": "PassModel", "required": [ "createdAt", "id", "programId", "status", "updatedAt" ], "type": "object", "properties": { "lastName": { "type": "string", "description": "Deprecated pass-level last name — use customer.lastName" }, "walletLink": { "required": [ "url" ], "type": "object", "properties": { "url": { "type": "string", "description": "The applicable wallet link: a pre-signed .pkpass download URL, an Apple Account binding secure URL, or a Google Wallet save link", "format": "uri" }, "expiresAt": { "type": "string", "description": "Link expiration timestamp. Omitted when the link does not expire.", "format": "date-time" } }, "additionalProperties": false, "description": "The short-lived upstream wallet artifact. Only present on POST /v1/passes and PATCH /v1/passes/{passId} when includeWalletLink=true and generation succeeded. Prefer the permanent link field, which is always returned." }, "walletType": { "type": "string", "description": "Wallet platform where pass is installed", "enum": [ "APPLE_WALLET", "GOOGLE_WALLET", "UNKNOWN" ] }, "companyName": { "maxLength": 200, "type": "string", "description": "Company name shown on the pass (employee passes)" }, "link": { "type": "string", "description": "Permanent public link for the pass. Never expires, safe to print and email; resolves at open time to the applicable wallet action. Append ?delivery=direct to 302 straight to the wallet artifact (the .pkpass file for Apple Wallet, the save link for Google Wallet) instead of the landing page.", "format": "uri" }, "employeeStartDate": { "type": "string", "description": "Employee start date shown on the pass (employee passes)", "format": "date-time" }, "idNumber": { "maxLength": 50, "type": "string", "description": "National/personal identity number shown on the pass" }, "entryState": { "type": "object", "additionalProperties": true, "description": "Entry-related state data" }, "expiredAt": { "type": "string", "description": "When the pass expired", "format": "date-time" }, "createdAt": { "type": "string", "description": "When the pass was created", "format": "date-time" }, "nfcPayload": { "maxLength": 64, "type": "string", "description": "NFC payload string" }, "id": { "pattern": "^pass-[0-9a-f-]+$", "type": "string", "description": "Unique pass identifier" }, "email": { "type": "string", "description": "Deprecated pass-level email address — use customer.emailAddress", "format": "email" }, "group": { "type": "string", "description": "Grouping identifier for related passes" }, "expirationDate": { "type": "string", "description": "Scheduled date when the pass expires", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the pass was last updated", "format": "date-time" }, "image": { "type": "string", "description": "Pass image reference" }, "entryType": { "type": "string", "description": "Entry rule type for access passes", "enum": [ "timeBased", "visitBased" ] }, "qrPayload": { "maxLength": 4296, "type": "string", "description": "QR code payload string" }, "creationSource": { "type": "object", "properties": { "reference": { "type": "string", "description": "Optional transaction/request ID" }, "method": { "type": "string", "description": "Specific method/endpoint/action used" }, "type": { "type": "string", "description": "Creation method type", "enum": [ "APPLE_VAS", "API", "MANUAL", "BULK", "CRM" ] } }, "additionalProperties": false, "description": "Deprecated: legacy creation-source tracking, present only on passes created before attribution existed. Read attribution instead." }, "templateOverrides": { "type": "object", "additionalProperties": true, "description": "Per-pass overrides of template fields and images" }, "externalId": { "type": "string", "description": "External system reference (e.g., CRM user ID)" }, "semanticTags": { "$ref": "#/components/schemas/SemanticTagsModel" }, "maxDistance": { "minimum": 1, "type": "integer", "description": "Maximum distance (meters) for Apple Wallet location notifications. Overrides template/program defaults." }, "isVoided": { "type": "boolean", "description": "Whether the pass has been voided" }, "membershipStatus": { "maxLength": 255, "type": "string", "description": "Merchant-defined account status (e.g., \"Active\", \"Suspended\", \"On Hold\")" }, "externalReference": { "type": "string", "description": "Additional external reference for integration with external systems" }, "firstName": { "type": "string", "description": "Deprecated pass-level first name — use customer.firstName" }, "googleWalletObjectId": { "type": "string", "description": "Google Wallet object identifier for the pass" }, "phoneNumber": { "type": "string", "description": "Deprecated pass-level phone number — use customer.mobileNumber" }, "attribution": { "type": "object", "properties": { "referrerHost": { "maxLength": 253, "type": "string", "description": "Referrer host only, never a full URL" }, "reference": { "maxLength": 200, "type": "string", "description": "Opaque correlation id: request id, endpoint id, session id" }, "origin": { "type": "string", "description": "STELL = a Stell-hosted surface, MERCHANT = the merchant's own code calling the API (default), PARTNER = a third-party connector acting for the merchant", "enum": [ "STELL", "MERCHANT", "PARTNER" ] }, "touchedAt": { "type": "string", "description": "When the attribution was recorded (server-stamped)", "format": "date-time" }, "channel": { "type": "string", "description": "Where the person came from. When omitted it is DECLARED from campaign.medium (email, sms, qr, print, terminal, social, paid, web) or otherwise INFERRED from the mechanism.", "enum": [ "EMAIL", "SMS", "QR", "PRINT", "TERMINAL", "SOCIAL", "PAID", "WEB", "DIRECT", "UNKNOWN" ] }, "campaign": { "type": "object", "properties": { "campaign": { "maxLength": 200, "type": "string" }, "term": { "maxLength": 200, "type": "string" }, "source": { "maxLength": 200, "type": "string" }, "medium": { "maxLength": 200, "type": "string" }, "content": { "maxLength": 200, "type": "string" } }, "additionalProperties": false, "description": "utm_* parameters as received" }, "mechanism": { "type": "string", "description": "How the pass was created. Named for what happened, never for which system did it.", "enum": [ "API", "VAS_PERSONALIZATION", "VAS_MEMBER_LINK", "ADMIN_FORM", "PORTAL_ISSUE", "ONBOARDING_FORM", "ONBOARDING_FORM_OTP", "ONBOARDING_FORM_IDENTITY", "PREBOARDING_LINK", "DIRECT_LINK", "EMBED_WIDGET", "APP_CLIP", "CRM_SYNC" ] }, "channelConfidence": { "type": "string", "description": "DECLARED when the channel came from utm_medium or the caller, INFERRED otherwise", "enum": [ "DECLARED", "INFERRED" ] }, "landingPath": { "maxLength": 200, "type": "string", "description": "Landing route template (e.g. /p/{nanoId}/{memberId}), never a real id" }, "identityProvider": { "pattern": "^[a-z0-9-]{1,50}$", "type": "string", "description": "Identity provider slug (e.g. vipps) the person authenticated with. Required with mechanism ONBOARDING_FORM_IDENTITY and rejected with 400 on any other mechanism." } }, "additionalProperties": false, "description": "Attribution: whose surface created the pass (origin), how it was created (mechanism) and where the person came from (channel + campaign). Every field is optional; absent fields default to origin MERCHANT, mechanism API, channel inferred, reference = request id." }, "loyaltyState": { "type": "object", "additionalProperties": true, "description": "Loyalty program state data (points, stamps, tier, vouchers)" }, "isExpired": { "type": "boolean", "description": "Whether the pass has expired" }, "activationDate": { "type": "string", "description": "Scheduled date when the pass becomes active", "format": "date-time" }, "voidedAt": { "type": "string", "description": "When the pass was voided", "format": "date-time" }, "programId": { "type": "string", "description": "ID of the program this pass belongs to" }, "employeeRole": { "maxLength": 100, "type": "string", "description": "Employee role shown on the pass (employee passes)" }, "status": { "type": "string", "description": "Current pass status", "enum": [ "PREACTIVE", "ACTIVE", "INACTIVE", "VOIDED", "REVOKED", "EXPIRED" ] }, "customer": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Customer's first name" }, "lastName": { "type": "string", "description": "Customer's last name" }, "emailAddress": { "type": "string", "description": "Customer's email address", "format": "email" }, "personalId": { "maxLength": 64, "type": "string", "description": "National/personal identity number (e.g., Swedish personnummer). Optional. PII — sent only when required by merchant." }, "lookupSource": { "maxLength": 50, "pattern": "^[a-z0-9-]+$", "type": "string", "description": "Which CRM was queried for new/existing determination (e.g., \"voyado\", \"bloomreach\")" }, "mobileNumber": { "type": "string", "description": "Customer's mobile number in E.164 format" }, "isNew": { "type": "boolean", "description": "Whether the customer was new (not found in merchant CRM) at pass creation time" } }, "additionalProperties": false, "description": "Customer information" } }, "description": "Digital pass issued to a customer." }, "AddPassGeofenceResponseModel": { "title": "AddPassGeofenceResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "id", "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters (optional)" }, "relevantText": { "type": "string", "description": "Message shown when user is near this location" }, "latitude": { "type": "number", "description": "Latitude in decimal degrees" }, "id": { "type": "string", "description": "Unique geofence identifier" }, "longitude": { "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "Created geofence" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "additionalProperties": false, "description": "Response from adding a geofence." }, "PassTemplateListModel": { "title": "PassTemplateListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "templates" ], "type": "object", "properties": { "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" }, "templates": { "type": "array", "description": "The templates in this page of results", "items": { "required": [ "createdAt", "id", "programId", "status", "updatedAt" ], "type": "object", "properties": { "backFields": { "type": "array", "description": "Back fields displayed on the pass", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "dateStyle": { "type": "string", "description": "Date formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "timeStyle": { "type": "string", "description": "Time formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "label": { "type": "string", "description": "Field label text" }, "localizedValue": { "type": "object", "description": "Localized values by language code" }, "dataDetectorTypes": { "type": "array", "description": "Data detector types", "items": { "type": "string", "enum": [ "PKDataDetectorTypePhoneNumber", "PKDataDetectorTypeLink", "PKDataDetectorTypeAddress", "PKDataDetectorTypeCalendarEvent" ] } }, "ignoresTimeZone": { "type": "boolean", "description": "Ignore timezone differences" }, "attributedValue": { "type": "string", "description": "Attributed value for rich text" }, "textAlignment": { "type": "string", "description": "Text alignment", "enum": [ "PKTextAlignmentLeft", "PKTextAlignmentCenter", "PKTextAlignmentRight", "PKTextAlignmentNatural" ] }, "localizedLabel": { "type": "object", "description": "Localized labels by language code" }, "changeMessage": { "type": "string", "description": "Message shown when value changes" }, "numberStyle": { "type": "string", "description": "Number formatting style", "enum": [ "PKNumberStyleDecimal", "PKNumberStylePercent", "PKNumberStyleScientific", "PKNumberStyleSpellOut" ] }, "row": { "type": "integer", "description": "Row number for auxiliary fields" }, "value": { "type": "string", "description": "Field value" }, "currencyCode": { "type": "string", "description": "ISO 4217 currency code" }, "isRelative": { "type": "boolean", "description": "Display as relative time" }, "key": { "type": "string", "description": "Unique field identifier" } }, "description": "One field item, shared by primaryFields, secondaryFields, auxiliaryFields, headerFields and backFields" } }, "transitType": { "type": "string", "description": "Transit type for boarding passes", "enum": [ "AIR", "BOAT", "BUS", "GENERIC", "TRAIN" ] }, "associatedStoreIdentifiers": { "type": "array", "description": "Associated App Store identifiers", "items": { "type": "string", "description": "App Store identifier" } }, "description": { "type": "string", "description": "Template description" }, "auxiliaryFields": { "type": "array", "description": "Auxiliary fields displayed on the pass", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "dateStyle": { "type": "string", "description": "Date formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "timeStyle": { "type": "string", "description": "Time formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "label": { "type": "string", "description": "Field label text" }, "localizedValue": { "type": "object", "description": "Localized values by language code" }, "dataDetectorTypes": { "type": "array", "description": "Data detector types", "items": { "type": "string", "enum": [ "PKDataDetectorTypePhoneNumber", "PKDataDetectorTypeLink", "PKDataDetectorTypeAddress", "PKDataDetectorTypeCalendarEvent" ] } }, "ignoresTimeZone": { "type": "boolean", "description": "Ignore timezone differences" }, "attributedValue": { "type": "string", "description": "Attributed value for rich text" }, "textAlignment": { "type": "string", "description": "Text alignment", "enum": [ "PKTextAlignmentLeft", "PKTextAlignmentCenter", "PKTextAlignmentRight", "PKTextAlignmentNatural" ] }, "localizedLabel": { "type": "object", "description": "Localized labels by language code" }, "changeMessage": { "type": "string", "description": "Message shown when value changes" }, "numberStyle": { "type": "string", "description": "Number formatting style", "enum": [ "PKNumberStyleDecimal", "PKNumberStylePercent", "PKNumberStyleScientific", "PKNumberStyleSpellOut" ] }, "row": { "type": "integer", "description": "Row number for auxiliary fields" }, "value": { "type": "string", "description": "Field value" }, "currencyCode": { "type": "string", "description": "ISO 4217 currency code" }, "isRelative": { "type": "boolean", "description": "Display as relative time" }, "key": { "type": "string", "description": "Unique field identifier" } }, "description": "One field item, shared by primaryFields, secondaryFields, auxiliaryFields, headerFields and backFields" } }, "colors": { "type": "object", "properties": { "backgroundColor": { "type": "string", "description": "Background color in hex format" }, "foregroundColor": { "type": "string", "description": "Foreground color in hex format" }, "stripColor": { "type": "string", "description": "Strip color in hex format" }, "labelColor": { "type": "string", "description": "Label color in hex format" } }, "description": "Pass color configuration" }, "createdAt": { "type": "string", "description": "When the template was created", "format": "date-time" }, "sharingProhibited": { "type": "boolean", "description": "Prohibit pass sharing" }, "defaultLanguage": { "type": "string", "description": "Default language code" }, "passStyle": { "type": "string", "description": "Style of the pass" }, "supportedLanguages": { "type": "array", "description": "Supported language codes", "items": { "type": "string", "description": "ISO 639-1 language code" } }, "headerFields": { "type": "array", "description": "Header fields displayed on the pass", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "dateStyle": { "type": "string", "description": "Date formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "timeStyle": { "type": "string", "description": "Time formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "label": { "type": "string", "description": "Field label text" }, "localizedValue": { "type": "object", "description": "Localized values by language code" }, "dataDetectorTypes": { "type": "array", "description": "Data detector types", "items": { "type": "string", "enum": [ "PKDataDetectorTypePhoneNumber", "PKDataDetectorTypeLink", "PKDataDetectorTypeAddress", "PKDataDetectorTypeCalendarEvent" ] } }, "ignoresTimeZone": { "type": "boolean", "description": "Ignore timezone differences" }, "attributedValue": { "type": "string", "description": "Attributed value for rich text" }, "textAlignment": { "type": "string", "description": "Text alignment", "enum": [ "PKTextAlignmentLeft", "PKTextAlignmentCenter", "PKTextAlignmentRight", "PKTextAlignmentNatural" ] }, "localizedLabel": { "type": "object", "description": "Localized labels by language code" }, "changeMessage": { "type": "string", "description": "Message shown when value changes" }, "numberStyle": { "type": "string", "description": "Number formatting style", "enum": [ "PKNumberStyleDecimal", "PKNumberStylePercent", "PKNumberStyleScientific", "PKNumberStyleSpellOut" ] }, "row": { "type": "integer", "description": "Row number for auxiliary fields" }, "value": { "type": "string", "description": "Field value" }, "currencyCode": { "type": "string", "description": "ISO 4217 currency code" }, "isRelative": { "type": "boolean", "description": "Display as relative time" }, "key": { "type": "string", "description": "Unique field identifier" } }, "description": "One field item, shared by primaryFields, secondaryFields, auxiliaryFields, headerFields and backFields" } }, "id": { "type": "string", "description": "Unique pass template identifier" }, "updatedAt": { "type": "string", "description": "When the template was last updated", "format": "date-time" }, "logoText": { "type": "string", "description": "Text displayed next to the logo" }, "organizationName": { "type": "string", "description": "Organization name displayed on the pass" }, "secondaryFields": { "type": "array", "description": "Secondary fields displayed on the pass", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "dateStyle": { "type": "string", "description": "Date formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "timeStyle": { "type": "string", "description": "Time formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "label": { "type": "string", "description": "Field label text" }, "localizedValue": { "type": "object", "description": "Localized values by language code" }, "dataDetectorTypes": { "type": "array", "description": "Data detector types", "items": { "type": "string", "enum": [ "PKDataDetectorTypePhoneNumber", "PKDataDetectorTypeLink", "PKDataDetectorTypeAddress", "PKDataDetectorTypeCalendarEvent" ] } }, "ignoresTimeZone": { "type": "boolean", "description": "Ignore timezone differences" }, "attributedValue": { "type": "string", "description": "Attributed value for rich text" }, "textAlignment": { "type": "string", "description": "Text alignment", "enum": [ "PKTextAlignmentLeft", "PKTextAlignmentCenter", "PKTextAlignmentRight", "PKTextAlignmentNatural" ] }, "localizedLabel": { "type": "object", "description": "Localized labels by language code" }, "changeMessage": { "type": "string", "description": "Message shown when value changes" }, "numberStyle": { "type": "string", "description": "Number formatting style", "enum": [ "PKNumberStyleDecimal", "PKNumberStylePercent", "PKNumberStyleScientific", "PKNumberStyleSpellOut" ] }, "row": { "type": "integer", "description": "Row number for auxiliary fields" }, "value": { "type": "string", "description": "Field value" }, "currencyCode": { "type": "string", "description": "ISO 4217 currency code" }, "isRelative": { "type": "boolean", "description": "Display as relative time" }, "key": { "type": "string", "description": "Unique field identifier" } }, "description": "One field item, shared by primaryFields, secondaryFields, auxiliaryFields, headerFields and backFields" } }, "semanticTags": { "$ref": "#/components/schemas/SemanticTagsModel" }, "primaryFields": { "type": "array", "description": "Primary fields displayed on the pass", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "dateStyle": { "type": "string", "description": "Date formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "timeStyle": { "type": "string", "description": "Time formatting style", "enum": [ "PKDateStyleNone", "PKDateStyleShort", "PKDateStyleMedium", "PKDateStyleLong", "PKDateStyleFull" ] }, "label": { "type": "string", "description": "Field label text" }, "localizedValue": { "type": "object", "description": "Localized values by language code" }, "dataDetectorTypes": { "type": "array", "description": "Data detector types", "items": { "type": "string", "enum": [ "PKDataDetectorTypePhoneNumber", "PKDataDetectorTypeLink", "PKDataDetectorTypeAddress", "PKDataDetectorTypeCalendarEvent" ] } }, "ignoresTimeZone": { "type": "boolean", "description": "Ignore timezone differences" }, "attributedValue": { "type": "string", "description": "Attributed value for rich text" }, "textAlignment": { "type": "string", "description": "Text alignment", "enum": [ "PKTextAlignmentLeft", "PKTextAlignmentCenter", "PKTextAlignmentRight", "PKTextAlignmentNatural" ] }, "localizedLabel": { "type": "object", "description": "Localized labels by language code" }, "changeMessage": { "type": "string", "description": "Message shown when value changes" }, "numberStyle": { "type": "string", "description": "Number formatting style", "enum": [ "PKNumberStyleDecimal", "PKNumberStylePercent", "PKNumberStyleScientific", "PKNumberStyleSpellOut" ] }, "row": { "type": "integer", "description": "Row number for auxiliary fields" }, "value": { "type": "string", "description": "Field value" }, "currencyCode": { "type": "string", "description": "ISO 4217 currency code" }, "isRelative": { "type": "boolean", "description": "Display as relative time" }, "key": { "type": "string", "description": "Unique field identifier" } }, "description": "One field item, shared by primaryFields, secondaryFields, auxiliaryFields, headerFields and backFields" } }, "maxDistance": { "type": "number", "description": "Maximum distance in meters for location relevance" }, "barcodes": { "type": "array", "description": "Barcode configurations", "items": { "required": [ "format", "messageEncoding", "payload" ], "type": "object", "properties": { "altText": { "type": "string", "description": "Alternative text displayed below barcode" }, "payload": { "type": "string", "description": "Barcode payload data" }, "format": { "type": "string", "description": "Barcode format", "enum": [ "PKBarcodeFormatQR", "PKBarcodeFormatPDF417", "PKBarcodeFormatAztec", "PKBarcodeFormatCode128" ] }, "messageEncoding": { "type": "string", "description": "Character encoding for the message" } }, "description": "One barcode representation of the pass" } }, "beacons": { "type": "array", "description": "iBeacon configurations for proximity-based notifications", "items": { "required": [ "name", "uuid" ], "type": "object", "properties": { "major": { "maximum": 65535, "minimum": 0, "type": "integer", "description": "Beacon major value (0-65535, optional - narrows beacon match)" }, "minor": { "maximum": 65535, "minimum": 0, "type": "integer", "description": "Beacon minor value (0-65535, optional - identifies specific beacon)" }, "name": { "type": "string", "description": "Human-readable beacon name for admin display" }, "lockScreenMessage": { "type": "string", "description": "Message displayed on lock screen when in beacon range (optional)" }, "uuid": { "type": "string", "description": "Beacon proximity UUID (8-4-4-4-12 hexadecimal format)" } }, "description": "One iBeacon proximity trigger" } }, "appLaunchURL": { "type": "string", "description": "URL to launch app when pass is tapped" }, "locations": { "type": "array", "description": "Pass-relevant locations", "items": { "type": "object", "properties": { "altitude": { "type": "number", "description": "Location altitude in meters" }, "relevantText": { "type": "string", "description": "Text shown when near location" }, "latitude": { "type": "number", "description": "Location latitude" }, "longitude": { "type": "number", "description": "Location longitude" } }, "description": "One geofence trigger point" } }, "programId": { "type": "string", "description": "ID of the program this template belongs to" }, "status": { "type": "string", "description": "Template status", "enum": [ "DRAFT", "ACTIVE", "INACTIVE", "ARCHIVED" ] } } } } }, "description": "Page of templates plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "TemplateOverridesModel": { "type": "object", "properties": { "logoText": { "maxLength": 50, "type": "string", "description": "Override logo text (max 50 characters)" }, "fieldOverrides": { "type": "object", "properties": { "backFields": { "type": "array", "description": "Override back fields", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "label": { "type": "string", "description": "Label shown above the value. Omit to keep the template label." }, "value": { "type": "string", "description": "Value shown on the pass" }, "key": { "type": "string", "description": "Key of the template field to override. Unknown keys add a new field." } }, "description": "One field override" } }, "secondaryFields": { "type": "array", "description": "Override secondary fields", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "label": { "type": "string", "description": "Label shown above the value. Omit to keep the template label." }, "value": { "type": "string", "description": "Value shown on the pass" }, "key": { "type": "string", "description": "Key of the template field to override. Unknown keys add a new field." } }, "description": "One field override" } }, "mergeStrategy": { "type": "string", "description": "Strategy for merging field overrides", "enum": [ "REPLACE", "MERGE", "APPEND" ], "default": "MERGE" }, "primaryFields": { "type": "array", "description": "Override primary fields", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "label": { "type": "string", "description": "Label shown above the value. Omit to keep the template label." }, "value": { "type": "string", "description": "Value shown on the pass" }, "key": { "type": "string", "description": "Key of the template field to override. Unknown keys add a new field." } }, "description": "One field override" } }, "headerFields": { "type": "array", "description": "Override header fields", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "label": { "type": "string", "description": "Label shown above the value. Omit to keep the template label." }, "value": { "type": "string", "description": "Value shown on the pass" }, "key": { "type": "string", "description": "Key of the template field to override. Unknown keys add a new field." } }, "description": "One field override" } }, "auxiliaryFields": { "type": "array", "description": "Override auxiliary fields", "items": { "required": [ "key", "value" ], "type": "object", "properties": { "label": { "type": "string", "description": "Label shown above the value. Omit to keep the template label." }, "value": { "type": "string", "description": "Value shown on the pass" }, "key": { "type": "string", "description": "Key of the template field to override. Unknown keys add a new field." } }, "description": "One field override" } } }, "description": "Override pass fields with custom values" }, "images": { "type": "object", "properties": { "footerImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Footer image above the barcode (boarding passes)." }, "artworkImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Poster artwork (poster event tickets). Apple Wallet only; there is no Google Wallet equivalent." }, "primaryLogoImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Poster header logo (poster event tickets and poster-capable generic passes). Apple Wallet only." }, "venueMapImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Venue map (poster event tickets). Stored at original dimensions. Apple Wallet only." }, "logoImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Logo shown in the pass header." }, "iconImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Icon used in notifications and on the lock screen." }, "secondaryLogoImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Secondary logo (poster event tickets). Apple Wallet only." }, "backgroundImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Background image (event tickets and generic passes)." }, "stripImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Strip image below the header. Also becomes the Google Wallet hero image." }, "thumbnailImage": { "type": "object", "properties": { "sourceUrl": { "maxLength": 2048, "type": "string", "description": "Public HTTPS URL that Stell fetches, validates, resizes and stores. Provide exactly one of sourceUrl or uploadId.", "format": "uri" }, "uploadId": { "maxLength": 512, "type": "string", "description": "Opaque upload identifier returned by POST /v1/passes/image-uploads. Provide exactly one of sourceUrl or uploadId." } }, "additionalProperties": false, "description": "Thumbnail image (generic passes and event tickets)." } }, "additionalProperties": false, "description": "Per-pass image overrides. Each slot accepts { \"sourceUrl\": \"https://...\" } or { \"uploadId\": \"...\" }. Set a slot to null to clear the override and fall back to the template image; omit a slot to keep its current value. On Google Wallet, stripImage becomes the hero image, and artworkImage is Apple Wallet only." }, "overrideMetadata": { "type": "object", "additionalProperties": true, "description": "Additional metadata for override context" }, "overrideReason": { "maxLength": 100, "type": "string", "description": "Reason for applying overrides (e.g., \"Gold member\", \"VIP status\")" }, "maxDistance": { "minimum": 1, "type": "integer", "description": "Maximum distance (meters) for Apple Wallet location notifications. Overrides template/program defaults. Send null to clear and revert to template/program defaults." }, "actions": { "type": "object", "description": "Pass-level featured actions. When non-empty, fully replaces the template actions array. Send null or an empty array to revert to the template actions." }, "colors": { "type": "object", "properties": { "backgroundColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Background color in hex format (e.g., \"#FF0000\")" }, "foregroundColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Foreground/text color in hex format" }, "stripColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Strip color in hex format" }, "labelColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Label color in hex format" } }, "description": "Override pass colors" } }, "additionalProperties": false, "description": "Template overrides for dynamic pass customization based on business logic (e.g., member tiers, promotions). All fields are optional." }, "CreatePassModel": { "title": "CreatePassModel", "required": [ "programId", "walletType" ], "type": "object", "properties": { "templateOverrides": { "$ref": "#/components/schemas/TemplateOverridesModel" }, "walletType": { "type": "string", "description": "Target wallet platform for the pass", "enum": [ "APPLE_WALLET", "GOOGLE_WALLET" ] }, "notificationMessage": { "type": "string", "description": "Message shown when the pass is updated (wallet push / pass refresh)" }, "externalId": { "type": "string", "description": "External reference ID from CRM or other systems" }, "semanticTagOverrides": { "$ref": "#/components/schemas/SemanticTagsModel" }, "membershipStatus": { "maxLength": 255, "type": "string", "description": "Merchant-defined account status (e.g., \"Active\", \"Suspended\", \"On Hold\")" }, "externalReference": { "maxLength": 200, "type": "string", "description": "Additional external reference for integration with external systems" }, "payload": { "type": "string", "description": "NFC or QR payload (defaults to pass ID if not provided)" }, "loyaltyState": { "type": "object", "properties": { "memberSince": { "type": "string", "description": "Date when customer became a member", "format": "date-time" }, "stampsCollected": { "type": "integer", "description": "Number of stamps collected" }, "terms": { "type": "string", "description": "Terms and conditions text for the pass" }, "pointsBalance": { "type": "integer", "description": "Current loyalty points balance" }, "voucherBalance": { "type": "number", "description": "Total monetary value of active vouchers" }, "description": { "type": "string", "description": "General description text for the pass (e.g., reward details)" }, "voucherCurrency": { "type": "string", "description": "Currency code for voucher balance (e.g., NOK)" }, "currentTierId": { "type": "string", "description": "Current tier identifier in loyalty program" }, "pendingPoints": { "type": "integer", "description": "Points pending activation (not yet redeemable)" }, "voucherCount": { "type": "integer", "description": "Number of active vouchers" }, "expirationDate": { "type": "string", "description": "Loyalty membership expiration date", "format": "date-time" } }, "description": "Loyalty program state information" }, "attribution": { "type": "object", "properties": { "referrerHost": { "maxLength": 253, "type": "string", "description": "Referrer host only, never a full URL" }, "reference": { "maxLength": 200, "type": "string", "description": "Opaque correlation id: request id, endpoint id, session id" }, "origin": { "type": "string", "description": "STELL = a Stell-hosted surface, MERCHANT = the merchant's own code calling the API (default), PARTNER = a third-party connector acting for the merchant", "enum": [ "STELL", "MERCHANT", "PARTNER" ] }, "channel": { "type": "string", "description": "Where the person came from. When omitted it is DECLARED from campaign.medium (email, sms, qr, print, terminal, social, paid, web) or otherwise INFERRED from the mechanism.", "enum": [ "EMAIL", "SMS", "QR", "PRINT", "TERMINAL", "SOCIAL", "PAID", "WEB", "DIRECT", "UNKNOWN" ] }, "campaign": { "type": "object", "properties": { "campaign": { "maxLength": 200, "type": "string" }, "term": { "maxLength": 200, "type": "string" }, "source": { "maxLength": 200, "type": "string" }, "medium": { "maxLength": 200, "type": "string" }, "content": { "maxLength": 200, "type": "string" } }, "additionalProperties": false, "description": "utm_* parameters as received" }, "mechanism": { "type": "string", "description": "How the pass was created. Named for what happened, never for which system did it.", "enum": [ "API", "VAS_PERSONALIZATION", "VAS_MEMBER_LINK", "ADMIN_FORM", "PORTAL_ISSUE", "ONBOARDING_FORM", "ONBOARDING_FORM_OTP", "ONBOARDING_FORM_IDENTITY", "PREBOARDING_LINK", "DIRECT_LINK", "EMBED_WIDGET", "APP_CLIP", "CRM_SYNC" ] }, "channelConfidence": { "type": "string", "description": "DECLARED when the channel came from utm_medium or the caller, INFERRED otherwise", "enum": [ "DECLARED", "INFERRED" ] }, "landingPath": { "maxLength": 200, "type": "string", "description": "Landing route template (e.g. /p/{nanoId}/{memberId}), never a real id" }, "identityProvider": { "pattern": "^[a-z0-9-]{1,50}$", "type": "string", "description": "Identity provider slug (e.g. vipps) the person authenticated with. Required with mechanism ONBOARDING_FORM_IDENTITY and rejected with 400 on any other mechanism." } }, "additionalProperties": false, "description": "Attribution: whose surface created the pass (origin), how it was created (mechanism) and where the person came from (channel + campaign). Every field is optional; absent fields default to origin MERCHANT, mechanism API, channel inferred, reference = request id." }, "activationDate": { "type": "string", "description": "Date when the pass becomes active", "format": "date-time" }, "programId": { "minLength": 1, "type": "string", "description": "ID of the program to create a pass for" }, "customer": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Customer first name for personalization" }, "lastName": { "type": "string", "description": "Customer last name for personalization" }, "emailAddress": { "type": "string", "description": "Customer email address for notifications", "format": "email" }, "personalId": { "maxLength": 64, "type": "string", "description": "National/personal identity number (e.g., Swedish personnummer). Optional. PII — sent only when required by merchant." }, "lookupSource": { "maxLength": 50, "pattern": "^[a-z0-9-]+$", "type": "string", "description": "Which CRM was queried for new/existing determination (e.g., \"voyado\", \"bloomreach\"). Slug format." }, "phone": { "type": "string", "description": "Customer phone number (deprecated - use mobileNumber)" }, "mobileNumber": { "type": "string", "description": "Customer mobile phone number for SMS delivery" }, "isNew": { "type": "boolean", "description": "Whether the customer is new (not found in merchant CRM). Set at creation, immutable." }, "email": { "type": "string", "description": "Customer email address (deprecated - use emailAddress)", "format": "email" } }, "description": "Optional customer information for personalization" }, "expirationDate": { "type": "string", "description": "Date when the pass expires", "format": "date-time" } }, "description": "Data required to create a pass." }, "CompanyModel": { "title": "CompanyModel", "required": [ "createdAt", "id", "name", "status", "updatedAt" ], "type": "object", "properties": { "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the company was created", "format": "date-time" }, "name": { "type": "string", "description": "Company name displayed in the system" }, "externalId": { "type": "string", "description": "External reference ID for integration with third-party systems" }, "id": { "type": "string", "description": "Unique company identifier in ULID format" }, "status": { "type": "string", "description": "Current operational status of the company", "enum": [ "PREACTIVE", "ACTIVE", "INACTIVE", "CLOSED" ] }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the company was last updated", "format": "date-time" } }, "description": "Top-level organization in your tenant hierarchy." }, "UpdatePassGeofenceModel": { "title": "UpdatePassGeofenceModel", "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters (optional)" }, "relevantText": { "maxLength": 100, "type": "string", "description": "Message shown when user is near this location" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude (-90 to 90)" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude (-180 to 180)" } }, "additionalProperties": false, "description": "Request to update a geofence on a pass." }, "ProgramResponseModel": { "title": "ProgramResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProgramModel" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response envelope carrying a program." }, "UpdateMerchantModel": { "title": "Update Merchant Request", "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Update merchant business name" }, "externalId": { "minLength": 1, "type": "string", "description": "Update external system identifier" }, "location": { "type": "object", "properties": { "phoneNumber": { "maxLength": 50, "type": "string", "description": "Contact phone number" }, "address": { "type": "object", "properties": { "country": { "maxLength": 2, "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "city": { "maxLength": 100, "type": "string", "description": "City name" }, "street": { "maxLength": 200, "type": "string", "description": "Street address" }, "postalCode": { "maxLength": 20, "type": "string", "description": "Postal or ZIP code" }, "state": { "maxLength": 100, "type": "string", "description": "State or province" } }, "additionalProperties": false, "description": "Postal address" }, "coordinate": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude coordinate" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude coordinate" } }, "additionalProperties": false, "description": "Geographic coordinate" }, "name": { "maxLength": 200, "type": "string", "description": "Location name" }, "description": { "maxLength": 500, "type": "string", "description": "Location description" } }, "additionalProperties": false, "description": "Update physical location details" }, "status": { "type": "string", "description": "Update merchant operational status", "enum": [ "PREACTIVE", "ACTIVE", "INACTIVE", "CLOSED" ] } } }, "UpdateTerminalModel": { "title": "UpdateTerminalModel", "type": "object", "properties": { "note": { "maxLength": 1000, "type": "string", "description": "Additional notes about the terminal" }, "serialNumber": { "maxLength": 100, "type": "string", "description": "Hardware serial number" }, "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Terminal display name" }, "externalId": { "maxLength": 255, "type": "string", "description": "External reference ID" }, "status": { "type": "string", "description": "Terminal operational status", "enum": [ "ONLINE", "OFFLINE", "SWITCHED_OFF", "MAINTENANCE", "ERROR" ] } }, "description": "Fields to update on an existing terminal." }, "CreatePassImageUploadModel": { "title": "Create Pass Image Upload Request", "required": [ "contentType" ], "type": "object", "properties": { "contentType": { "type": "string", "description": "MIME type the upload PUT will send. Only PNG and JPEG images are accepted.", "enum": [ "image/png", "image/jpeg" ] } }, "additionalProperties": false }, "BatchCreatePassesModel": { "title": "BatchCreatePassesModel", "required": [ "passes", "programId" ], "type": "object", "properties": { "passes": { "maxItems": 1000, "minItems": 1, "type": "array", "description": "Array of passes to create (1-1000 items)", "items": { "required": [ "walletType" ], "type": "object", "properties": { "templateOverrides": { "type": "object", "additionalProperties": true, "description": "Template overrides for this pass. Same shape as single pass creation: images.{slot} accepts { \"sourceUrl\": \"https://...\" } or { \"uploadId\": \"...\" }, and null clears the slot." }, "payload": { "maxLength": 64, "type": "string", "description": "NFC/QR payload string (max 64 chars)" }, "walletType": { "type": "string", "description": "Target wallet platform for the pass", "enum": [ "APPLE_WALLET", "GOOGLE_WALLET" ] }, "loyaltyState": { "type": "object", "additionalProperties": true, "description": "Loyalty program state data" }, "notificationMessage": { "type": "string", "description": "Message shown when the pass is updated (wallet push / pass refresh)" }, "attribution": { "type": "object", "properties": { "referrerHost": { "maxLength": 253, "type": "string", "description": "Referrer host only, never a full URL" }, "reference": { "maxLength": 200, "type": "string", "description": "Opaque correlation id: request id, endpoint id, session id" }, "origin": { "type": "string", "description": "STELL = a Stell-hosted surface, MERCHANT = the merchant's own code calling the API (default), PARTNER = a third-party connector acting for the merchant", "enum": [ "STELL", "MERCHANT", "PARTNER" ] }, "channel": { "type": "string", "description": "Where the person came from. When omitted it is DECLARED from campaign.medium (email, sms, qr, print, terminal, social, paid, web) or otherwise INFERRED from the mechanism.", "enum": [ "EMAIL", "SMS", "QR", "PRINT", "TERMINAL", "SOCIAL", "PAID", "WEB", "DIRECT", "UNKNOWN" ] }, "campaign": { "type": "object", "properties": { "campaign": { "maxLength": 200, "type": "string" }, "term": { "maxLength": 200, "type": "string" }, "source": { "maxLength": 200, "type": "string" }, "medium": { "maxLength": 200, "type": "string" }, "content": { "maxLength": 200, "type": "string" } }, "additionalProperties": false, "description": "utm_* parameters as received" }, "mechanism": { "type": "string", "description": "How the pass was created. Named for what happened, never for which system did it.", "enum": [ "API", "VAS_PERSONALIZATION", "VAS_MEMBER_LINK", "ADMIN_FORM", "PORTAL_ISSUE", "ONBOARDING_FORM", "ONBOARDING_FORM_OTP", "ONBOARDING_FORM_IDENTITY", "PREBOARDING_LINK", "DIRECT_LINK", "EMBED_WIDGET", "APP_CLIP", "CRM_SYNC" ] }, "channelConfidence": { "type": "string", "description": "DECLARED when the channel came from utm_medium or the caller, INFERRED otherwise", "enum": [ "DECLARED", "INFERRED" ] }, "landingPath": { "maxLength": 200, "type": "string", "description": "Landing route template (e.g. /p/{nanoId}/{memberId}), never a real id" }, "identityProvider": { "pattern": "^[a-z0-9-]{1,50}$", "type": "string", "description": "Identity provider slug (e.g. vipps) the person authenticated with. Required with mechanism ONBOARDING_FORM_IDENTITY and rejected with 400 on any other mechanism." } }, "additionalProperties": false, "description": "Attribution: whose surface created the pass (origin), how it was created (mechanism) and where the person came from (channel + campaign). Every field is optional; absent fields default to origin MERCHANT, mechanism API, channel inferred, reference = request id." }, "externalId": { "maxLength": 100, "type": "string", "description": "External reference ID from CRM or other systems (max 100 chars)" }, "activationDate": { "type": "string", "description": "ISO 8601 date when the pass becomes active", "format": "date-time" }, "entryState": { "type": "object", "additionalProperties": true, "description": "Entry-related state data" }, "customer": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Customer first name" }, "lastName": { "type": "string", "description": "Customer last name" }, "emailAddress": { "type": "string", "description": "Customer email address", "format": "email" }, "personalId": { "maxLength": 64, "type": "string", "description": "National/personal identity number (e.g., Swedish personnummer). Optional. PII — sent only when required by merchant." }, "lookupSource": { "maxLength": 50, "pattern": "^[a-z0-9-]+$", "type": "string", "description": "Which CRM was queried for new/existing determination (e.g., \"voyado\")" }, "mobileNumber": { "type": "string", "description": "Customer mobile phone number" }, "isNew": { "type": "boolean", "description": "Whether the customer is new (not found in merchant CRM). Set at creation, immutable." } }, "additionalProperties": true, "description": "Customer information for personalization" }, "expirationDate": { "type": "string", "description": "ISO 8601 date when the pass expires", "format": "date-time" } }, "description": "One pass to create within the batch" } }, "options": { "type": "object", "properties": { "stopOnError": { "type": "boolean", "description": "Stop processing on first error (default: false)" }, "skipDuplicates": { "type": "boolean", "description": "Skip passes where externalId already exists (default: false)" } }, "description": "Batch processing options" }, "programId": { "minLength": 1, "type": "string", "description": "ID of the program to create passes for (all passes in batch use the same program)" } }, "description": "Request to batch create multiple passes." }, "Error401Model": { "title": "Error401Model", "required": [ "error", "requestId" ], "type": "object", "properties": { "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" }, "error": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "UNAUTHORIZED" ] }, "details": { "type": "object", "additionalProperties": true, "description": "Additional error context" }, "message": { "type": "string", "description": "Human-readable error message", "default": "Authentication required" } }, "description": "Error information" } }, "description": "Authentication failed." }, "PassEncryptionKeysResponseModel": { "title": "PassEncryptionKeys Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "createdAt", "id", "privateKey", "programId", "publicKey" ], "type": "object", "properties": { "privateKey": { "minLength": 20, "type": "string", "description": "ECDH P-256 private key in PEM format" }, "createdAt": { "type": "string", "description": "Timestamp when the key was created (ISO format)", "format": "date-time" }, "description": { "type": "string", "description": "Optional description of the key" }, "id": { "type": "string", "description": "Encryption key ID" }, "publicKey": { "minLength": 20, "type": "string", "description": "ECDH P-256 public key in PEM format" }, "publicKeyUncompressed": { "minLength": 20, "type": "string", "description": "ECDH P-256 public key in uncompressed PEM format (for Google Smart Tap)" }, "programId": { "type": "string", "description": "Program ID this key belongs to" } }, "additionalProperties": false, "description": "PassEncryptionKeys details" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "additionalProperties": false }, "UpdatePassGeofencesResponseModel": { "title": "Update Pass Geofences Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "count", "message" ], "type": "object", "properties": { "count": { "type": "integer", "description": "Number of geofences set on the pass" }, "message": { "type": "string", "description": "Descriptive message about the result" } }, "additionalProperties": false, "description": "Geofence update result" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "additionalProperties": false }, "SemanticTagsModel": { "type": "object", "properties": { "eventLiveMessage": { "maxLength": 500, "type": "string", "description": "Real-time event status updates (iOS 18+)" }, "leagueAbbreviation": { "type": "string", "description": "Sports league abbreviation (e.g., NFL, MLB)" }, "venuePhoneNumber": { "type": "string", "description": "Venue contact phone number" }, "priorityStatus": { "type": "string", "description": "Priority boarding or check-in status" }, "tailgatingAllowed": { "type": "boolean", "description": "" }, "seats": { "maxItems": 10, "type": "array", "description": "Seat assignments for events, flights, or venues", "items": { "type": "object", "properties": { "seatIdentifier": { "maxLength": 50, "type": "string", "description": "Unique seat identifier combining all components" }, "seatType": { "maxLength": 30, "type": "string", "description": "Type or category of seat" }, "seatDescription": { "maxLength": 100, "type": "string", "description": "Additional seat information" }, "seatSection": { "maxLength": 20, "type": "string", "description": "Section identifier (e.g., Orchestra, Balcony, A)" }, "seatRow": { "maxLength": 10, "type": "string", "description": "Row identifier (e.g., 12, A, Front)" }, "seatAisle": { "maxLength": 10, "type": "string", "description": "Aisle identifier" }, "seatSectionColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Color code for section visualization" }, "seatNumber": { "maxLength": 10, "type": "string", "description": "Seat number or identifier" }, "seatLevel": { "maxLength": 10, "type": "string", "description": "Level or floor identifier" } }, "additionalProperties": false, "description": "One seat assignment" } }, "attendeeName": { "maxLength": 100, "type": "string", "description": "Full name of the attendee" }, "leagueName": { "type": "string", "description": "Sports league full name" }, "securityScreening": { "type": "string", "description": "Security screening type (e.g., TSA PreCheck)" }, "venueEntrance": { "type": "string", "description": "Venue entrance name or identifier" }, "destinationGate": { "maxLength": 10, "type": "string", "description": "Arrival gate identifier" }, "balance": { "required": [ "amount", "currencyCode" ], "type": "object", "properties": { "amount": { "pattern": "^\\d+(\\.\\d{1,2})?$", "type": "string", "description": "Amount as string for precision (e.g., \"150.75\")" }, "currencyCode": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR, GBP)" } }, "additionalProperties": false, "description": "Account balance for loyalty programs or stored value cards" }, "playlistIDs": { "type": "array", "description": "List of playlist identifiers", "items": { "type": "string", "description": "Playlist identifier" } }, "eventName": { "maxLength": 200, "type": "string", "description": "Name of the event" }, "vehicleNumber": { "type": "string", "description": "Vehicle or route number" }, "airplay": { "type": "array", "description": "AirPlay device configuration", "items": { "required": [ "airPlayDeviceGroupToken" ], "type": "object", "properties": { "airPlayDeviceGroupToken": { "type": "string", "description": "Token for AirPlay device group identification" } }, "description": "One AirPlay device" } }, "homeTeamLocation": { "type": "string", "description": "Home team city or location" }, "silenceRequested": { "type": "boolean", "description": "Whether silent mode is requested for notifications" }, "awayTeamAbbreviation": { "maxLength": 10, "type": "string", "description": "Away team abbreviation for sports events" }, "departureAirportCode": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "IATA departure airport code" }, "vehicleType": { "type": "string", "description": "Type of vehicle (e.g., Bus, Train, Ferry)" }, "departurePlatform": { "maxLength": 20, "type": "string", "description": "Train departure platform" }, "awayTeamLocation": { "maxLength": 50, "type": "string", "description": "Away team city or location" }, "destinationLocationDescription": { "maxLength": 100, "type": "string", "description": "Descriptive destination location" }, "boardingSequenceNumber": { "maxLength": 10, "type": "string", "description": "Boarding sequence or position number" }, "venueEntrancePortal": { "type": "string", "description": "" }, "additionalTicketAttributes": { "maxLength": 200, "type": "string", "description": "Additional ticket features and benefits" }, "destinationAirportName": { "maxLength": 100, "type": "string", "description": "Full destination airport name" }, "membershipProgramNumber": { "type": "string", "description": "Member identification number" }, "venueOpenDate": { "type": "string", "description": "When the venue opens", "format": "date-time" }, "eventType": { "type": "string", "description": "Category of event this pass is for", "enum": [ "PKEventTypeGeneric", "PKEventTypeMovie", "PKEventTypeConference", "PKEventTypeConvention", "PKEventTypeWorkshop", "PKEventTypeSocialGathering", "PKEventTypeSports", "PKEventTypeLivePerformance" ] }, "admissionLevelAbbreviation": { "maxLength": 10, "type": "string", "description": "Short form of admission level" }, "currentBoardingDate": { "type": "string", "description": "Updated boarding date and time", "format": "date-time" }, "flightNumber": { "type": "number", "description": "Flight number without airline code" }, "artistIDs": { "type": "array", "description": "List of artist identifiers", "items": { "type": "string", "description": "Artist identifier" } }, "carNumber": { "maxLength": 20, "type": "string", "description": "Train car or vehicle number" }, "venueName": { "type": "string", "description": "Name of the venue or location" }, "eventStartDateInfo": { "required": [ "date" ], "type": "object", "properties": { "date": { "type": "string", "description": "Event start date in ISO 8601 format" }, "ignoreTimeComponents": { "type": "boolean", "description": "Whether to ignore time components and use date only" }, "timeZone": { "type": "string", "description": "Time zone identifier (e.g., America/New_York)" } }, "description": "Event start date with timezone control" }, "confirmationNumber": { "maxLength": 50, "type": "string", "description": "Booking or reservation confirmation number" }, "venueParkingLotsOpenDate": { "type": "string", "description": "When the venue parking lots open", "format": "date-time" }, "originalBoardingDate": { "type": "string", "description": "Originally scheduled boarding date and time", "format": "date-time" }, "awayTeamName": { "maxLength": 50, "type": "string", "description": "Full away team name" }, "albumIDs": { "type": "array", "description": "List of album identifiers", "items": { "type": "string", "description": "Album identifier" } }, "destinationPlatform": { "maxLength": 20, "type": "string", "description": "Train arrival platform" }, "homeTeamAbbreviation": { "type": "string", "description": "Home team abbreviation (e.g., NYY)" }, "sportName": { "type": "string", "description": "Name of the sport" }, "departureAirportName": { "maxLength": 100, "type": "string", "description": "Full departure airport name" }, "venueLocation": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "Venue location coordinates for events and venues" }, "wifiAccess": { "type": "array", "description": "WiFi network information", "items": { "required": [ "password", "ssid" ], "type": "object", "properties": { "password": { "type": "string", "description": "WiFi network password" }, "ssid": { "type": "string", "description": "WiFi network name (SSID)" } }, "description": "One WiFi network" } }, "eventStartDate": { "type": "string", "description": "When the event starts", "format": "date-time" }, "passengerName": { "type": "object", "properties": { "namePrefix": { "maxLength": 10, "type": "string", "description": "Name prefix (Mr., Ms., Dr., etc.)" }, "familyName": { "maxLength": 50, "type": "string", "description": "Last name/surname" }, "givenName": { "maxLength": 50, "type": "string", "description": "First name" }, "nickname": { "maxLength": 30, "type": "string", "description": "Preferred name or nickname" }, "nameSuffix": { "maxLength": 10, "type": "string", "description": "Name suffix (Jr., Sr., III, etc.)" }, "middleName": { "maxLength": 30, "type": "string", "description": "Middle name or initial" }, "phoneticRepresentation": { "maxLength": 100, "type": "string", "description": "Phonetic spelling for pronunciation" } }, "additionalProperties": false, "description": "Passenger name components for boarding passes" }, "destinationAirportCode": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "IATA destination airport code" }, "vehicleName": { "type": "string", "description": "Name of the vehicle or service" }, "entranceDescription": { "maxLength": 200, "type": "string", "description": "Description of the entrance location (iOS 18+)" }, "departureGate": { "maxLength": 10, "type": "string", "description": "Departure gate identifier" }, "totalPrice": { "required": [ "amount", "currencyCode" ], "type": "object", "properties": { "amount": { "pattern": "^\\d+(\\.\\d{1,2})?$", "type": "string", "description": "Amount as string for precision (e.g., \"29.99\")" }, "currencyCode": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR, GBP)" } }, "additionalProperties": false, "description": "Total price for transactions or purchases" }, "venueEntranceGate": { "type": "string", "description": "" }, "venueRoom": { "type": "string", "description": "Room or hall within the venue" }, "venueFanZoneOpenDate": { "type": "string", "description": "When the venue fan zone opens", "format": "date-time" }, "venueBoxOfficeOpenDate": { "type": "string", "description": "", "format": "date-time" }, "destinationLocation": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "Destination location coordinates for transit passes" }, "departureLocationDescription": { "maxLength": 100, "type": "string", "description": "Descriptive departure location" }, "originalDepartureDate": { "type": "string", "description": "Originally scheduled departure date and time", "format": "date-time" }, "duration": { "type": "number", "description": "Duration in seconds" }, "boardingGroup": { "maxLength": 20, "type": "string", "description": "Flight boarding group identifier" }, "currentDepartureDate": { "type": "string", "description": "Updated departure date and time", "format": "date-time" }, "destinationTerminal": { "maxLength": 20, "type": "string", "description": "Airport arrival terminal" }, "genre": { "type": "string", "description": "Event genre or category" }, "airlineCode": { "pattern": "^[A-Z0-9]{2,3}$", "type": "string", "description": "IATA airline code (2-3 characters)" }, "currentArrivalDate": { "type": "string", "description": "Updated arrival date and time", "format": "date-time" }, "admissionLevel": { "maxLength": 50, "type": "string", "description": "Access level or tier" }, "originalArrivalDate": { "type": "string", "description": "Originally scheduled arrival date and time", "format": "date-time" }, "eventEndDate": { "type": "string", "description": "When the event ends", "format": "date-time" }, "departureTerminal": { "maxLength": 20, "type": "string", "description": "Airport departure terminal" }, "membershipProgramName": { "type": "string", "description": "Name of the membership or loyalty program" }, "transitProvider": { "type": "string", "description": "Transit company or provider name" }, "departureLocation": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "Departure location coordinates for transit passes" }, "flightCode": { "type": "string", "description": "Airline IATA code (e.g., AA for American Airlines)" }, "transitStatusReason": { "type": "string", "description": "Reason for transit status if delayed or canceled" }, "venueGatesOpenDate": { "type": "string", "description": "When the venue gates open", "format": "date-time" }, "venueEntranceDoor": { "type": "string", "description": "" }, "performerNames": { "type": "array", "description": "List of performer names", "items": { "type": "string", "description": "Performer name" } }, "venueDoorsOpenDate": { "type": "string", "description": "", "format": "date-time" }, "transitStatus": { "type": "string", "description": "Current transit status (e.g., On Time, Delayed)" }, "venueRegionName": { "type": "string", "description": "" }, "departureStationName": { "maxLength": 100, "type": "string", "description": "Departure station name" }, "homeTeamName": { "type": "string", "description": "Home team full name" }, "destinationStationName": { "maxLength": 100, "type": "string", "description": "Destination station name" }, "venueCloseDate": { "type": "string", "description": "", "format": "date-time" } }, "additionalProperties": false, "description": "Semantic tags for Apple Wallet passes: seating, flight, event and location details that Wallet and Siri use for suggestions. All fields are optional; send the ones that apply to your pass type." }, "CreatePassTemplateModel": { "title": "Create Pass Template Request", "type": "object", "properties": { "userInfo": { "type": "object", "additionalProperties": true, "description": "Custom user information stored with the pass" }, "backFields": { "type": "array", "description": "Fields displayed on the back of the pass", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "transitType": { "type": "string", "description": "Transit type shown on boarding passes. Required when passStyle is BOARDING_PASS", "enum": [ "AIR", "BOAT", "BUS", "GENERIC", "TRAIN" ] }, "associatedStoreIdentifiers": { "type": "array", "description": "Associated App Store app identifiers", "items": { "type": "string", "description": "App Store identifier" } }, "description": { "maxLength": 500, "type": "string", "description": "Pass template description" }, "publicKey": { "type": "string", "description": "Public key for pass authentication" }, "auxiliaryFields": { "type": "array", "description": "Auxiliary fields displayed in a supporting role", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "enableGoogleSmartTap": { "type": "boolean", "description": "Enable Google Smart Tap for NFC interactions" }, "colors": { "type": "object", "properties": { "backgroundColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Background color in hex format" }, "foregroundColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Foreground color in hex format" }, "stripColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Strip color in hex format" }, "labelColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Label color in hex format" } }, "additionalProperties": false, "description": "Color scheme configuration for the pass" }, "sharingProhibited": { "type": "boolean", "description": "Whether pass sharing is prohibited" }, "defaultLanguage": { "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "type": "string", "description": "Default language code for the pass" }, "passStyle": { "type": "string", "description": "Visual style of the pass template", "enum": [ "GENERIC_CARD", "COUPON", "EVENT_TICKET", "BOARDING_PASS", "STORE_CARD" ] }, "supportedLanguages": { "type": "array", "description": "Supported language codes for localization", "items": { "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "type": "string", "description": "IETF BCP 47 language tag" } }, "headerFields": { "type": "array", "description": "Header fields displayed at the top of the pass", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "expirationDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", "type": "string", "description": "Pass expiration date in ISO 8601 format" }, "logoText": { "maxLength": 50, "type": "string", "description": "Text displayed next to the logo" }, "organizationName": { "maxLength": 100, "type": "string", "description": "Organization name displayed on the pass" }, "relevantDates": { "type": "array", "description": "Lock-screen relevance entries. Each entry is either a single moment ({ relevantDate }) or an interval ({ startDate, endDate }), all in ISO 8601 format.", "items": { "type": "object", "properties": { "endDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", "type": "string", "description": "Interval end (must be within 24 hours of startDate)" }, "relevantDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", "type": "string", "description": "Single moment the pass becomes relevant (mutually exclusive with startDate/endDate)" }, "startDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", "type": "string", "description": "Interval start (used with endDate; triggers an event-ticket Live Activity)" } }, "description": "One relevance entry: a single moment or an interval" } }, "secondaryFields": { "type": "array", "description": "Secondary fields displayed below primary fields", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "semanticTags": { "$ref": "#/components/schemas/SemanticTagsModel" }, "maxDistance": { "minimum": 1, "type": "integer", "description": "Maximum distance in meters for location relevance" }, "primaryFields": { "type": "array", "description": "Primary fields displayed prominently on the pass", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "barcodes": { "type": "array", "description": "Barcode configurations for the pass", "items": { "type": "object", "additionalProperties": true, "description": "One barcode configuration (shape defined by the target wallet platform)" } }, "sharing": { "type": "string", "description": "Pass sharing configuration" }, "beacons": { "type": "array", "description": "Beacon configurations for proximity notifications", "items": { "type": "object", "additionalProperties": true, "description": "One iBeacon proximity trigger (shape defined by the target wallet platform)" } }, "personalize": { "type": "object", "additionalProperties": true, "description": "Personalization configuration for the pass" }, "appLaunchURL": { "type": "string", "description": "URL to launch when pass is tapped", "format": "uri" }, "messages": { "type": "array", "description": "Custom messages for the pass", "items": { "type": "string", "description": "One custom message" } }, "locations": { "type": "array", "description": "Location-based notifications for the pass", "items": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters (optional)" }, "relevantText": { "maxLength": 100, "type": "string", "description": "Message shown when user is near this location" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "One geofence trigger point" } }, "status": { "type": "string", "description": "Initial template lifecycle status (defaults to DRAFT)", "enum": [ "DRAFT", "ACTIVE", "INACTIVE" ] } }, "additionalProperties": false, "description": "Request body for creating a new pass template within a program" }, "UpdatePassModel": { "title": "UpdatePassModel", "type": "object", "properties": { "externalReference": { "maxLength": 200, "type": "string", "description": "Additional external reference for integration with external systems" }, "templateOverrides": { "$ref": "#/components/schemas/TemplateOverridesModel" }, "payload": { "type": "string", "description": "NFC or QR payload (defaults to pass ID if not provided)" }, "loyaltyState": { "type": "object", "properties": { "memberSince": { "type": "string", "description": "Date when customer became a member. Pass null to clear.", "format": "date-time", "nullable": true }, "stampsCollected": { "type": "integer", "description": "Number of stamps collected" }, "terms": { "type": "string", "description": "Terms and conditions text for the pass" }, "pointsBalance": { "type": "integer", "description": "Current loyalty points balance" }, "voucherBalance": { "type": "number", "description": "Total monetary value of active vouchers" }, "description": { "type": "string", "description": "General description text for the pass (e.g., reward details)" }, "voucherCurrency": { "type": "string", "description": "Currency code for voucher balance (e.g., SEK)" }, "currentTierId": { "type": "string", "description": "Current tier identifier in loyalty program" }, "pendingPoints": { "type": "integer", "description": "Points pending activation (not yet redeemable)" }, "voucherCount": { "type": "integer", "description": "Number of active vouchers" }, "expirationDate": { "type": "string", "description": "Loyalty membership expiration date. Pass null to clear.", "format": "date-time", "nullable": true } }, "description": "Loyalty program state information" }, "notificationMessage": { "type": "string", "description": "Message shown when the pass is updated (wallet push / pass refresh)" }, "externalId": { "type": "string", "description": "External system reference (e.g., CRM user ID)" }, "activationDate": { "type": "string", "description": "Date when the pass becomes active. Pass null to clear.", "format": "date-time", "nullable": true }, "semanticTagOverrides": { "$ref": "#/components/schemas/SemanticTagsModel" }, "membershipStatus": { "maxLength": 255, "type": "string", "description": "Merchant-defined account status (e.g., \"Active\", \"Suspended\", \"On Hold\")" }, "status": { "type": "string", "description": "Update pass status (ACTIVE enables pass, VOIDED permanently disables)", "enum": [ "PREACTIVE", "ACTIVE", "INACTIVE", "VOIDED", "REVOKED", "EXPIRED" ] }, "customer": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Customer first name for personalization" }, "lastName": { "type": "string", "description": "Customer last name for personalization" }, "emailAddress": { "type": "string", "description": "Customer email address for notifications", "format": "email" }, "personalId": { "maxLength": 64, "type": "string", "description": "National/personal identity number (e.g., Swedish personnummer). Optional. PII — sent only when required by merchant." }, "phone": { "type": "string", "description": "Customer phone number (deprecated - use mobileNumber)" }, "mobileNumber": { "type": "string", "description": "Customer mobile phone number for SMS delivery" }, "email": { "type": "string", "description": "Customer email address (deprecated - use emailAddress)", "format": "email" } }, "description": "Update customer information" }, "expirationDate": { "type": "string", "description": "Date when the pass expires. Pass null to clear.", "format": "date-time", "nullable": true } }, "description": "Fields to update on an existing pass." }, "UpdatePassGeofencesModel": { "title": "UpdatePassGeofencesModel", "required": [ "geofences" ], "type": "object", "properties": { "geofences": { "maxItems": 10, "minItems": 0, "type": "array", "description": "Array of geofences to set as pass overrides", "items": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters (optional)" }, "relevantText": { "maxLength": 100, "type": "string", "description": "Message shown when user is near this location" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "One geofence trigger point" } } }, "additionalProperties": false, "description": "Fields to update pass geofence settings." }, "CreateTransactionModel": { "title": "CreateTransactionModel", "required": [ "passId", "type" ], "type": "object", "properties": { "tapMode": { "type": "string", "description": "Whether pass and payment were captured in one terminal tap (SINGLE_TAP), separate taps (DOUBLE_TAP), or without a terminal (NONE)", "enum": [ "SINGLE_TAP", "DOUBLE_TAP", "NONE" ] }, "pointsSpent": { "minimum": 0, "type": "integer", "description": "Loyalty points redeemed in this transaction" }, "passId": { "type": "string", "description": "ID of the pass to record transaction for" }, "channel": { "type": "string", "description": "Where the customer was: IN_STORE or ONLINE", "enum": [ "IN_STORE", "ONLINE" ] }, "instrument": { "type": "string", "description": "How the pass was presented (Apple VAS, Google Smart Tap, QR, NFC, MIFARE). The payment method goes in payment.method.", "enum": [ "APPLE_VAS", "GOOGLE_SMART_TAP", "QR", "NFC_TYPE_1", "NFC_TYPE_2", "NFC_TYPE_3", "NFC_TYPE_4", "NFC_TYPE_5", "MIFARE", "OTHER" ] }, "remainingUsesBefore": { "type": "integer", "description": "Number of remaining uses before this transaction (for access control)" }, "terminalId": { "type": "string", "description": "ID of the terminal that processed the transaction" }, "storeId": { "type": "string", "description": "ID of the store where transaction occurred" }, "type": { "type": "string", "description": "What happened to the pass. Use channel for in-store vs online and tapMode for single- vs double-tap; the legacy ONLINE / PASS_AND_PAYMENT / PASS_ONLY / PAYMENT_ONLY values are rejected.", "enum": [ "PURCHASE", "REDEMPTION", "POINTS_ADJUSTMENT", "SCAN_ONLY", "CHECK_IN", "CHECK_OUT", "UNKNOWN" ] }, "transactionDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})?$", "type": "string", "description": "ISO 8601 timestamp when transaction occurred (defaults to now). Accepts both timezone-bearing (2026-06-02T12:13:14Z) and timezone-less (2026-06-02T12:13:14, treated as UTC) forms." }, "reference": { "maxLength": 255, "type": "string", "description": "External transaction reference or receipt number" }, "pointsEarned": { "minimum": 0, "type": "integer", "description": "Loyalty points earned in this transaction" }, "statusReason": { "maxLength": 500, "type": "string", "description": "Reason for transaction status (e.g., denial reason)" }, "remainingUsesAfter": { "type": "integer", "description": "Number of remaining uses after this transaction (for access control)" }, "payment": { "type": "object", "properties": { "reference": { "maxLength": 255, "type": "string", "description": "Payment reference identifier" }, "amount": { "required": [ "currency", "value" ], "type": "object", "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR, GBP)" }, "value": { "minimum": 0, "type": "number", "description": "Payment amount value" } }, "additionalProperties": false, "description": "Payment amount details" }, "method": { "type": "string", "description": "How the customer paid (Apple Pay, Google Pay, card, cash, Vipps, MobilePay, ...)", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "CARD", "CASH", "VIPPS", "MOBILEPAY", "OTHER" ] }, "pspReference": { "maxLength": 255, "type": "string", "description": "Payment service provider reference" } }, "additionalProperties": false, "description": "Payment details for the transaction" }, "additionalData": { "type": "object", "properties": { "posRegisterId": { "type": "string", "description": "Identifier of the Point of Sale register" }, "lineItems": { "type": "array", "description": "Line items involved in the transaction", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "Quantity of the line item" }, "color": { "type": "string", "description": "Color of the line item" }, "itemCategory": { "type": "string", "description": "Category of the line item" }, "amountExcludingTax": { "type": "object", "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR, GBP)" }, "value": { "type": "number", "description": "The value of the amount" } }, "additionalProperties": false, "description": "A monetary amount" }, "taxPercentage": { "type": "number", "description": "Tax percentage for the line item" }, "description": { "type": "string", "description": "Description of the line item" }, "upc": { "type": "string", "description": "UPC of the line item" }, "manufacturer": { "type": "string", "description": "Manufacturer of the line item" }, "size": { "type": "string", "description": "Size of the line item" }, "imageUrl": { "type": "string", "description": "Image URL of the line item" }, "amountIncludingTax": { "type": "object", "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR, GBP)" }, "value": { "type": "number", "description": "The value of the amount" } }, "additionalProperties": false, "description": "A monetary amount" }, "productUrl": { "type": "string", "description": "Product URL of the line item" }, "sku": { "type": "string", "description": "SKU of the line item" }, "taxAmount": { "type": "object", "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR, GBP)" }, "value": { "type": "number", "description": "The value of the amount" } }, "additionalProperties": false, "description": "A monetary amount" }, "brand": { "type": "string", "description": "Brand of the line item" } }, "additionalProperties": false } }, "posEftPosText": { "type": "string", "description": "Text from the Point of Sale Electronic Funds Transfer system" }, "pos": { "type": "string", "description": "Point of Sale identifier" }, "posData": { "type": "object", "additionalProperties": true, "description": "Additional data from the Point of Sale system (arbitrary JSON)" }, "pspData": { "type": "object", "additionalProperties": true, "description": "Additional data from the Payment Service Provider (arbitrary JSON)" }, "mcc": { "type": "integer", "description": "Merchant Category Code as per ISO 18245:2023" } }, "additionalProperties": false, "description": "Custom data attached to the transaction. Only pos, posData, posRegisterId, posEftPosText, pspData, mcc, and lineItems are accepted — posData/pspData accept arbitrary JSON, everything else does not." }, "status": { "type": "string", "description": "Transaction status", "enum": [ "APPROVED", "DENIED", "FAILED", "PENDING" ] } }, "description": "Data required to record a new transaction." }, "Error400Model": { "title": "Error400Model", "required": [ "error", "requestId" ], "type": "object", "properties": { "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" }, "error": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "BAD_REQUEST" ] }, "details": { "type": "object", "additionalProperties": true, "description": "Additional error context" }, "message": { "type": "string", "description": "Human-readable error message", "default": "Invalid request parameters" } }, "description": "Error information" } }, "description": "Bad request with validation details." }, "UpdatePassTemplateModel": { "title": "Update Pass Template Request", "type": "object", "properties": { "userInfo": { "type": "object", "additionalProperties": true, "description": "Custom user information stored with the pass" }, "backFields": { "type": "array", "description": "Fields displayed on the back of the pass", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "transitType": { "type": "string", "description": "Transit type shown on boarding passes. Required when passStyle is BOARDING_PASS", "enum": [ "AIR", "BOAT", "BUS", "GENERIC", "TRAIN" ] }, "associatedStoreIdentifiers": { "type": "array", "description": "Associated App Store app identifiers", "items": { "type": "string", "description": "App Store identifier" } }, "description": { "maxLength": 500, "type": "string", "description": "Pass template description" }, "publicKey": { "type": "string", "description": "Public key for pass authentication" }, "auxiliaryFields": { "type": "array", "description": "Auxiliary fields displayed in a supporting role", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "enableGoogleSmartTap": { "type": "boolean", "description": "Enable Google Smart Tap for NFC interactions" }, "colors": { "type": "object", "properties": { "backgroundColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Background color in hex format" }, "foregroundColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Foreground color in hex format" }, "stripColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Strip color in hex format" }, "labelColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "description": "Label color in hex format" } }, "additionalProperties": false, "description": "Color scheme configuration for the pass" }, "sharingProhibited": { "type": "boolean", "description": "Whether pass sharing is prohibited" }, "defaultLanguage": { "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "type": "string", "description": "Default language code for the pass" }, "passStyle": { "type": "string", "description": "Visual style of the pass template", "enum": [ "GENERIC_CARD", "COUPON", "EVENT_TICKET", "BOARDING_PASS", "STORE_CARD" ] }, "supportedLanguages": { "type": "array", "description": "Supported language codes for localization", "items": { "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "type": "string", "description": "IETF BCP 47 language tag" } }, "headerFields": { "type": "array", "description": "Header fields displayed at the top of the pass", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "expirationDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", "type": "string", "description": "Pass expiration date in ISO 8601 format" }, "logoText": { "maxLength": 50, "type": "string", "description": "Text displayed next to the logo" }, "organizationName": { "maxLength": 100, "type": "string", "description": "Organization name displayed on the pass" }, "relevantDates": { "type": "array", "description": "Lock-screen relevance entries. Each entry is either a single moment ({ relevantDate }) or an interval ({ startDate, endDate }), all in ISO 8601 format.", "items": { "type": "object", "properties": { "endDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", "type": "string", "description": "Interval end (must be within 24 hours of startDate)" }, "relevantDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", "type": "string", "description": "Single moment the pass becomes relevant (mutually exclusive with startDate/endDate)" }, "startDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$", "type": "string", "description": "Interval start (used with endDate; triggers an event-ticket Live Activity)" } }, "description": "One relevance entry: a single moment or an interval" } }, "secondaryFields": { "type": "array", "description": "Secondary fields displayed below primary fields", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "semanticTags": { "$ref": "#/components/schemas/SemanticTagsModel" }, "maxDistance": { "minimum": 1, "type": "integer", "description": "Maximum distance in meters for location relevance" }, "primaryFields": { "type": "array", "description": "Primary fields displayed prominently on the pass", "items": { "type": "object", "additionalProperties": true, "description": "One field item (shape defined by the target wallet platform)" } }, "barcodes": { "type": "array", "description": "Barcode configurations for the pass", "items": { "type": "object", "additionalProperties": true, "description": "One barcode configuration (shape defined by the target wallet platform)" } }, "sharing": { "type": "string", "description": "Pass sharing configuration" }, "beacons": { "type": "array", "description": "Beacon configurations for proximity notifications", "items": { "type": "object", "additionalProperties": true, "description": "One iBeacon proximity trigger (shape defined by the target wallet platform)" } }, "personalize": { "type": "object", "additionalProperties": true, "description": "Personalization configuration for the pass" }, "appLaunchURL": { "type": "string", "description": "URL to launch when pass is tapped", "format": "uri" }, "messages": { "type": "array", "description": "Custom messages for the pass", "items": { "type": "string", "description": "One custom message" } }, "locations": { "type": "array", "description": "Location-based notifications for the pass", "items": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters (optional)" }, "relevantText": { "maxLength": 100, "type": "string", "description": "Message shown when user is near this location" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "One geofence trigger point" } }, "status": { "type": "string", "description": "Update template lifecycle status", "enum": [ "DRAFT", "ACTIVE", "INACTIVE", "ARCHIVED" ] } }, "additionalProperties": false, "description": "Request body for updating an existing pass template. All fields are optional — only include fields you want to change." }, "AddPassGeofenceModel": { "title": "AddPassGeofenceModel", "required": [ "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters (optional)" }, "relevantText": { "maxLength": 100, "type": "string", "description": "Message shown when user is near this location" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude (-90 to 90)" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude (-180 to 180)" } }, "additionalProperties": false, "description": "Request to add a geofence to a pass." }, "GoogleWalletLinkModel": { "title": "GoogleWalletLinkModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "addToWalletUrl", "expiresAt", "passId" ], "type": "object", "properties": { "googleWalletObjectId": { "type": "string", "description": "Google Wallet object identifier" }, "passId": { "type": "string", "description": "Unique identifier for the pass" }, "addToWalletUrl": { "type": "string", "description": "URL to add pass to Google Wallet", "format": "uri" }, "expiresAt": { "type": "string", "description": "Link expiration timestamp", "format": "date-time" } }, "additionalProperties": false, "description": "Google Wallet link data" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "additionalProperties": false, "description": "Google Wallet save link and metadata." }, "UpdatePassGeofenceResponseModel": { "title": "UpdatePassGeofenceResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "id", "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters (optional)" }, "relevantText": { "type": "string", "description": "Message shown when user is near this location" }, "latitude": { "type": "number", "description": "Latitude in decimal degrees" }, "id": { "type": "string", "description": "Unique geofence identifier" }, "longitude": { "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "Updated geofence" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "additionalProperties": false, "description": "Response from updating a geofence." }, "StoreResponseModel": { "title": "StoreResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StoreModel" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response envelope carrying a store." }, "BatchCreatePassesResponseModel": { "title": "BatchCreatePassesResponseModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "results", "summary" ], "type": "object", "properties": { "summary": { "required": [ "failed", "processingTimeMs", "skipped", "succeeded", "total" ], "type": "object", "properties": { "total": { "type": "integer", "description": "Total passes in request" }, "processingTimeMs": { "type": "integer", "description": "Total processing time in milliseconds" }, "failed": { "type": "integer", "description": "Passes that failed to create" }, "succeeded": { "type": "integer", "description": "Passes created successfully" }, "skipped": { "type": "integer", "description": "Passes skipped (duplicates)" } }, "description": "Batch processing summary" }, "results": { "type": "array", "description": "Per-pass results in request order", "items": { "required": [ "index", "status" ], "type": "object", "properties": { "passId": { "type": "string", "description": "ID of created pass (when status=created)" }, "link": { "type": "string", "description": "Permanent public link for the created pass (when status=created). Never expires; resolves at open time to the applicable wallet action. Append ?delivery=direct to 302 straight to the wallet artifact instead of the landing page.", "format": "uri" }, "index": { "type": "integer", "description": "Position in original request array" }, "externalId": { "type": "string", "description": "External ID from request" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Human-readable error message" } }, "description": "Error details (when status=failed)" }, "status": { "type": "string", "description": "Result status for this pass", "enum": [ "created", "failed", "skipped" ] } }, "description": "Result for one pass from the batch request" } } }, "description": "Batch creation summary and per-pass results" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "description": "Response from batch pass creation." }, "PassTemplateModel": { "title": "PassTemplate", "type": "object", "properties": { "userInfo": { "type": "object", "description": "Custom user information object (Apple Wallet)" }, "backFields": { "type": "array", "description": "Back of pass fields" }, "transitType": { "type": "string", "description": "Transit type for boarding passes", "enum": [ "AIR", "BOAT", "BUS", "GENERIC", "TRAIN" ] }, "associatedStoreIdentifiers": { "type": "array", "description": "Associated App Store identifiers (Apple Wallet)", "items": { "type": "string", "description": "App Store identifier" } }, "description": { "type": "string", "description": "Pass description" }, "auxiliaryFields": { "type": "array", "description": "Auxiliary display fields" }, "colors": { "type": "object", "properties": { "backgroundColor": { "type": "string", "description": "RGB color (e.g., \"rgb(255,255,255)\")" }, "foregroundColor": { "type": "string", "description": "RGB color for text" }, "stripColor": { "type": "string", "description": "RGB color for strip" }, "labelColor": { "type": "string", "description": "RGB color for labels" } }, "description": "Pass color configuration" }, "createdAt": { "type": "string", "description": "Template creation timestamp", "format": "date-time" }, "sharingProhibited": { "type": "boolean", "description": "Whether pass sharing is disabled" }, "defaultLanguage": { "type": "string", "description": "Default language code (ISO 639-1)" }, "passStyle": { "type": "string", "description": "Pass visual style", "enum": [ "generic", "boardingPass", "coupon", "eventTicket", "storeCard" ] }, "supportedLanguages": { "type": "array", "description": "Array of supported language codes (ISO 639-1)", "items": { "type": "string", "description": "ISO 639-1 language code" } }, "headerFields": { "type": "array", "description": "Header display fields" }, "id": { "type": "string", "description": "Unique template identifier" }, "expirationDate": { "type": "string", "description": "When the pass expires", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Last update timestamp", "format": "date-time" }, "logoText": { "type": "string", "description": "Text to display as logo" }, "organizationName": { "type": "string", "description": "Organization name on the pass" }, "secondaryFields": { "type": "array", "description": "Secondary display fields" }, "relevantDates": { "type": "array", "description": "Lock-screen relevance entries. Each entry is a single moment ({ relevantDate }) or an interval ({ startDate, endDate }).", "items": { "type": "object", "properties": { "endDate": { "type": "string", "description": "Interval end (used with startDate)", "format": "date-time" }, "relevantDate": { "type": "string", "description": "Single moment the pass becomes relevant", "format": "date-time" }, "startDate": { "type": "string", "description": "Interval start (used with endDate)", "format": "date-time" } }, "description": "One relevance entry: a single moment or an interval" } }, "semanticTags": { "$ref": "#/components/schemas/SemanticTagsModel" }, "primaryFields": { "type": "array", "description": "Primary display fields" }, "maxDistance": { "type": "number", "description": "Maximum distance in meters for location-based triggers" }, "barcodes": { "type": "array", "description": "Barcode configurations", "items": { "type": "object", "properties": { "altText": { "type": "string", "description": "Human-readable text displayed near the barcode" }, "format": { "type": "string", "description": "Barcode symbology to render", "enum": [ "PKBarcodeFormatQR", "PKBarcodeFormatPDF417", "PKBarcodeFormatAztec", "PKBarcodeFormatCode128" ] }, "messageEncoding": { "type": "string", "description": "Text encoding used for the message (e.g., \"iso-8859-1\")" }, "message": { "type": "string", "description": "Data encoded in the barcode" } }, "description": "One barcode representation of the pass" } }, "sharing": { "type": "string", "description": "Sharing configuration object as JSON string" }, "beacons": { "type": "array", "description": "Beacon configurations for proximity detection", "items": { "type": "object", "properties": { "relevantText": { "type": "string", "description": "Message shown on the lock screen when the device is near this beacon" }, "major": { "type": "number", "description": "iBeacon major value" }, "minor": { "type": "number", "description": "iBeacon minor value" }, "uuid": { "type": "string", "description": "iBeacon proximity UUID" } }, "description": "One iBeacon proximity trigger" } }, "personalize": { "type": "object", "description": "Personalization configuration for pass fields" }, "appLaunchURL": { "type": "string", "description": "URL to launch when pass is tapped (Apple Wallet)" }, "locations": { "type": "array", "description": "Location-based triggers", "items": { "type": "object", "properties": { "relevantText": { "type": "string", "description": "Message shown on the lock screen when the device enters this location" }, "latitude": { "type": "number", "description": "Latitude in decimal degrees" }, "maxDistance": { "type": "number", "description": "Maximum distance in meters from the location that still counts as relevant" }, "longitude": { "type": "number", "description": "Longitude in decimal degrees" } }, "description": "One geofence trigger point" } }, "programId": { "type": "string", "description": "Associated program identifier" }, "status": { "type": "string", "description": "Template status", "enum": [ "DRAFT", "ACTIVE", "INACTIVE" ] } }, "additionalProperties": false }, "Error403Model": { "title": "Error403Model", "required": [ "error", "requestId" ], "type": "object", "properties": { "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" }, "error": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "FORBIDDEN" ] }, "details": { "type": "object", "additionalProperties": true, "description": "Additional error context" }, "message": { "type": "string", "description": "Human-readable error message", "default": "Access denied to this resource" } }, "description": "Error information" } }, "description": "Access denied." }, "TerminalListModel": { "title": "TerminalListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "terminals" ], "type": "object", "properties": { "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" }, "terminals": { "type": "array", "description": "The terminals in this page of results", "items": { "required": [ "createdAt", "id", "storeId", "updatedAt" ], "type": "object", "properties": { "note": { "type": "string", "description": "Additional notes about the terminal" }, "createdAt": { "type": "string", "description": "When the terminal was created", "format": "date-time" }, "serialNumber": { "type": "string", "description": "Hardware serial number" }, "name": { "type": "string", "description": "Terminal display name" }, "externalId": { "type": "string", "description": "External reference ID" }, "id": { "type": "string", "description": "Unique terminal identifier" }, "storeId": { "type": "string", "description": "ID of the store this terminal belongs to" }, "status": { "type": "string", "description": "Terminal operational status", "enum": [ "ACTIVE", "INACTIVE", "OFFLINE" ] }, "updatedAt": { "type": "string", "description": "When the terminal was last updated", "format": "date-time" } } } } }, "description": "Page of terminals plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "StoreListModel": { "title": "StoreListModel Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "stores" ], "type": "object", "properties": { "stores": { "type": "array", "description": "The stores in this page of results", "items": { "required": [ "createdAt", "id", "merchantId", "name", "updatedAt" ], "type": "object", "properties": { "createdAt": { "type": "string", "description": "When the store was created", "format": "date-time" }, "merchantId": { "type": "string", "description": "Parent merchant ID" }, "name": { "type": "string", "description": "Store name" }, "externalId": { "type": "string", "description": "External system identifier" }, "location": { "type": "object", "properties": { "country": { "type": "string", "description": "Country code" }, "address": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City name" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "latitude": { "type": "number", "description": "Latitude coordinate" }, "state": { "type": "string", "description": "State or province" }, "longitude": { "type": "number", "description": "Longitude coordinate" } }, "description": "Store's physical address and coordinates" }, "id": { "type": "string", "description": "Unique store identifier" }, "updatedAt": { "type": "string", "description": "When the store was last updated", "format": "date-time" } } } }, "nextToken": { "type": "string", "description": "Pagination cursor for fetching the next page, absent on the last page" } }, "description": "Page of stores plus the pagination cursor" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } } }, "GeofenceListModel": { "title": "GeofenceListModel", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "geofences", "metadata" ], "type": "object", "properties": { "metadata": { "required": [ "maxAllowed", "passOverrideCount", "programGeofenceCount", "totalCount" ], "type": "object", "properties": { "maxAllowed": { "type": "integer", "description": "Maximum number of geofences allowed", "enum": [ 10 ] }, "programGeofenceCount": { "maximum": 10, "minimum": 0, "type": "integer", "description": "Number of program-level geofences" }, "passOverrideCount": { "maximum": 10, "minimum": 0, "type": "integer", "description": "Number of pass-level override geofences" }, "totalCount": { "maximum": 10, "minimum": 0, "type": "integer", "description": "Total number of geofences" } }, "additionalProperties": false, "description": "Metadata about the geofences" }, "geofences": { "maxItems": 10, "type": "array", "description": "List of geofences", "items": { "required": [ "latitude", "longitude", "source" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters (optional)" }, "relevantText": { "maxLength": 100, "type": "string", "description": "Message shown when user is near this location" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude in decimal degrees" }, "id": { "type": "string", "description": "Unique identifier for the geofence" }, "source": { "type": "string", "description": "Origin of the geofence", "enum": [ "PROGRAM", "PASS_OVERRIDE" ] }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude in decimal degrees" } }, "additionalProperties": false, "description": "One geofence trigger point" } } }, "additionalProperties": false, "description": "Geofence data" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "additionalProperties": false, "description": "Geofences associated with a pass." }, "CreateMerchantModel": { "title": "Create Merchant Request", "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Merchant business name (1-200 characters)" }, "externalId": { "minLength": 1, "type": "string", "description": "External system identifier for integration" }, "location": { "type": "object", "properties": { "phoneNumber": { "maxLength": 50, "type": "string", "description": "Contact phone number" }, "address": { "type": "object", "properties": { "country": { "maxLength": 2, "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "city": { "maxLength": 100, "type": "string", "description": "City name" }, "street": { "maxLength": 200, "type": "string", "description": "Street address" }, "postalCode": { "maxLength": 20, "type": "string", "description": "Postal or ZIP code" }, "state": { "maxLength": 100, "type": "string", "description": "State or province" } }, "additionalProperties": false, "description": "Postal address" }, "coordinate": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "altitude": { "type": "number", "description": "Altitude in meters" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number", "description": "Latitude coordinate" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number", "description": "Longitude coordinate" } }, "additionalProperties": false, "description": "Geographic coordinate" }, "name": { "maxLength": 200, "type": "string", "description": "Location name" }, "description": { "maxLength": 500, "type": "string", "description": "Location description" } }, "additionalProperties": false, "description": "Physical location details for the merchant" } } }, "HealthModel": { "title": "Health Check Response", "required": [ "status", "timestamp" ], "type": "object", "properties": { "environment": { "type": "string", "description": "Current deployment environment (present when healthy)" }, "service": { "type": "string", "description": "Name of the service (present when healthy)" }, "region": { "type": "string", "description": "AWS region where the service is running (present when healthy)" }, "error": { "type": "string", "description": "Error message describing the health check failure (present when unhealthy)" }, "version": { "type": "string", "description": "API version (present when healthy)" }, "status": { "type": "string", "description": "Health status of the service", "enum": [ "healthy", "unhealthy" ] }, "timestamp": { "type": "string", "description": "Current server timestamp in ISO 8601 format", "format": "date-time" } } }, "PassImageUploadResponseModel": { "title": "Pass Image Upload Response", "required": [ "data", "requestId" ], "type": "object", "properties": { "data": { "required": [ "expiresAt", "uploadId", "uploadUrl" ], "type": "object", "properties": { "uploadUrl": { "type": "string", "description": "Upload URL. Send the image bytes with a PUT request and the declared Content-Type header.", "format": "uri" }, "uploadId": { "type": "string", "description": "Opaque upload identifier to reference as templateOverrides.images.{slot}.uploadId on pass create or update." }, "expiresAt": { "type": "string", "description": "When the upload URL expires (15 minutes). Staged uploads not promoted within 24 hours are deleted.", "format": "date-time" } }, "additionalProperties": false, "description": "Upload slot details" }, "requestId": { "pattern": "^[0-9A-Z]{26}$", "type": "string", "description": "Unique request identifier for debugging" } }, "additionalProperties": false } }, "securitySchemes": { "StellApiAuthorizer": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key authentication. Include your API key as a Bearer token.\n\nExample: `Bearer sk_prod_xxxxxx`\n\nGet your API key from the Stell Dashboard." } } }, "x-amazon-apigateway-security-policy": "TLS_1_0", "security": [ { "StellApiAuthorizer": [] } ] }