> ## Documentation Index > Fetch the complete documentation index at: https://docs.getstell.com/llms.txt > Use this file to discover all available pages before exploring further. # Create transaction > Record a new transaction against a pass. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/transactions 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-08-09T18:16:19Z' servers: - url: https://api.platform.getstell.com description: Production API security: - StellApiAuthorizer: [] 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/transactions: 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: [] components: schemas: CreateTransactionModel: title: CreateTransactionModel required: - passId - storeId - type type: object properties: pointsSpent: minimum: 0 type: integer description: Loyalty points redeemed in this transaction passId: type: string description: ID of the pass to record transaction for instrument: type: string description: Payment method used for the transaction enum: - CARD - CASH - MOBILE - OTHER - APPLE_VAS - GOOGLE_SMART_TAP - QR - NFC_TYPE_1 - NFC_TYPE_2 - NFC_TYPE_3 - NFC_TYPE_4 - NFC_TYPE_5 - MIFARE 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: Type of transaction being recorded enum: - ONLINE - PASS_AND_PAYMENT - PASS_ONLY - PAYMENT_ONLY - 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 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. 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. 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. 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. 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. 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. 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. TransactionModel: title: TransactionModel required: - createdAt - id - passId - storeId - transactionDate - type - updatedAt type: object properties: pointsSpent: type: number description: Loyalty points redeemed in this transaction passId: type: string description: ID of the pass associated with this transaction instrument: type: string description: Transaction instrument used enum: - CARD - CASH - MOBILE - OTHER - APPLE_VAS - GOOGLE_SMART_TAP - QR - NFC_TYPE_1 - NFC_TYPE_2 - NFC_TYPE_3 - NFC_TYPE_4 - NFC_TYPE_5 - MIFARE 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: Transaction type enum: - ONLINE - PASS_AND_PAYMENT - PASS_ONLY - PAYMENT_ONLY - SCAN_ONLY - CHECK_IN - CHECK_OUT - UNKNOWN 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 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. securitySchemes: StellApiAuthorizer: type: http scheme: bearer bearerFormat: API Key description: |- API key authentication. Include your API key as a Bearer token. Example: `Bearer sk_prod_xxxxxx` Get your API key from the Stell Dashboard. ````