> ## Documentation Index > Fetch the complete documentation index at: https://help.vori.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a gift card transaction > Records a credit or debit against a specific gift card and moves its balance by the amount. Supply an idempotency key so a retry returns the transaction already recorded rather than moving the balance twice. ## OpenAPI ````yaml /api/openapi.json post /v1/gift-cards/{id}/transactions openapi: 3.0.0 info: title: Vori API description: '' version: 1.0.0 contact: {} servers: - url: https://api.vori.com description: production security: [] tags: [] paths: /v1/gift-cards/{id}/transactions: post: tags: - Gift cards summary: Create a gift card transaction description: >- Records a credit or debit against a specific gift card and moves its balance by the amount. Supply an idempotency key so a retry returns the transaction already recorded rather than moving the balance twice. operationId: createGiftCardTransaction parameters: - name: id required: true in: path schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGiftCardTransactionRequest' responses: '201': description: Gift card transaction created successfully. content: application/json: schema: $ref: '#/components/schemas/GiftCardTransaction' '400': description: '' content: application/json: schema: anyOf: - $ref: '#/components/schemas/DuplicateIdempotencyKeyError' - $ref: '#/components/schemas/GiftCardDeactivatedError' - $ref: '#/components/schemas/InsufficientGiftCardBalanceError' - $ref: '#/components/schemas/InvalidEmployeeError' - $ref: '#/components/schemas/InvalidStoreError' - $ref: '#/components/schemas/InvalidTopupAmountError' - $ref: '#/components/schemas/InvalidUserError' - $ref: '#/components/schemas/MissingEmployeeError' - $ref: '#/components/schemas/MissingOrderError' - $ref: '#/components/schemas/MissingStoreError' - $ref: '#/components/schemas/UnexpectedEmployeeError' - $ref: '#/components/schemas/UnexpectedOrderError' - $ref: '#/components/schemas/UnexpectedTransactionTypeError' '403': description: '' content: application/json: schema: anyOf: - $ref: '#/components/schemas/InsufficientPermissionsError' - $ref: '#/components/schemas/NoBannerAssociationError' '404': description: Gift card not found. security: - bearer: [] components: schemas: CreateGiftCardTransactionRequest: type: object properties: amount: type: string description: Amount to be added or removed from the gift card format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ description: type: string description: Description to write alongside the transaction employee_id: type: string description: >- ID of the employee responsible. Only a register sends one, and it is required there; a back-office session records the signed-in user, and an API credential records itself. idempotency_key: type: string description: >- Idempotency key to avoid duplicate transactions. Only one transaction may exist with a given idempotency key. Subsequent requests with the same idempotency key will return the data persisted in the database. order_id: type: string description: >- ID of the checkout this transaction is tied to, from the transactions resource. Only a register sends one. store_id: type: string description: >- ID of the store the transaction belongs to. Optional: name a store to attribute the adjustment to it, or omit it for one that is not tied to a store. pattern: ^[0-9]+$ type: description: >- The kind of transaction. An API client may only send `manual_adjustment`; the other types are recorded at the point of sale. allOf: - $ref: '#/components/schemas/GiftCardTransactionType' required: - amount - idempotency_key - type GiftCardTransaction: type: object properties: id: type: string description: Unique identifier for the record. amount: type: string description: >- Money the transaction moved on the card. A positive amount adds funds; a negative amount spends them. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ api_client_id: type: string nullable: true description: >- ID of the API credential that recorded the transaction. Null when a person did. created_at: type: string description: When the record was created. format: date-time description: type: string nullable: true description: >- Note written alongside the transaction, such as why an adjustment was made. effective_at: type: string description: >- When the transaction took effect. A sale carries the time it was completed at the register, so this can be earlier than `created_at`, which is when the transaction was recorded on the ledger. format: date-time employee_id: type: string nullable: true description: >- ID of the employee who took the transaction at a register, or null when it was made in the back office or by an API credential. pattern: ^[0-9]+$ idempotency_key: type: string description: >- Key supplied when the transaction was created, unique within the banner. Sending the same key again returns the transaction already recorded rather than moving the balance twice. order_id: type: string nullable: true description: >- ID of the checkout this transaction is tied to, from the transactions resource. Null when the transaction is not tied to a checkout. format: uuid store_id: type: string nullable: true description: >- ID of the store where the transaction took place. Null for a transaction not tied to a store, such as a back-office adjustment. pattern: ^[0-9]+$ type: description: >- What produced the transaction: funds loaded onto the card, the card spent on a sale or restored by a refund, or a back-office adjustment. allOf: - $ref: '#/components/schemas/GiftCardTransactionType' updated_at: type: string description: When the record was last changed. format: date-time user_id: type: string nullable: true description: >- ID of the back-office user who made the transaction. Null for a transaction taken at a register or by an API credential. pattern: ^[0-9]+$ description: >- One credit or debit on a gift card. The ledger is append-only, so a transaction is never edited or removed once recorded; a correction is another transaction. required: - id - amount - api_client_id - created_at - description - effective_at - employee_id - idempotency_key - order_id - store_id - type - updated_at - user_id DuplicateIdempotencyKeyError: type: object properties: error_code: type: string enum: - duplicate_idempotency_key required: - error_code GiftCardDeactivatedError: type: object properties: error_code: type: string enum: - gift_card_deactivated required: - error_code InsufficientGiftCardBalanceError: type: object properties: error_code: type: string enum: - insufficient_gift_card_balance required: - error_code InvalidEmployeeError: type: object properties: error_code: type: string enum: - invalid_employee required: - error_code InvalidStoreError: type: object properties: error_code: type: string enum: - invalid_store required: - error_code InvalidTopupAmountError: type: object properties: error_code: type: string enum: - invalid_topup_amount required: - error_code InvalidUserError: type: object properties: error_code: type: string enum: - invalid_user required: - error_code MissingEmployeeError: type: object properties: error_code: type: string enum: - missing_employee required: - error_code MissingOrderError: type: object properties: error_code: type: string enum: - missing_order required: - error_code MissingStoreError: type: object properties: error_code: type: string enum: - missing_store required: - error_code UnexpectedEmployeeError: type: object properties: error_code: type: string enum: - unexpected_employee required: - error_code UnexpectedOrderError: type: object properties: error_code: type: string enum: - unexpected_order required: - error_code UnexpectedTransactionTypeError: type: object properties: error_code: type: string enum: - unexpected_transaction_type required: - error_code InsufficientPermissionsError: type: object properties: error_code: type: string enum: - insufficient_permissions error_details: $ref: '#/components/schemas/InsufficientPermissionsErrorDetails' required: - error_code - error_details NoBannerAssociationError: type: object properties: error_code: type: string enum: - no_banner_association required: - error_code GiftCardTransactionType: type: string enum: - book_transfer - funding_from_payment - manual_adjustment - order_payment InsufficientPermissionsErrorDetails: type: object properties: action: allOf: - $ref: '#/components/schemas/Action' resource: allOf: - $ref: '#/components/schemas/Resource' required: - action - resource Action: type: string enum: - '*' - cancel - check_in - create - delete - read - read_credentials - record_events - refund - restart - update - void Resource: type: string enum: - '*' - accounting_integration - agent_chats - api_clients - asynchronous_tasks - banners - blackhawk_transactions - capabilities - coupons - custom_quick_actions - datacap_transactions - departments - discounts - ditto_auth_tokens - edge_agents - electronic_shelf_labels - employees - feature_orientations - files - food_modifiers - gift_cards - gl_code_mappings - house_accounts - inventory - inventory_sessions - inventory_settings - invoices - item_modifiers - label_dimension_sets - label_sheet_profiles - label_stock_products - lanes - loyalty_bonuses - loyalty_campaigns - loyalty_rewards - notification_templates - offers - order_guides - pos_banner_configurations - pos_orders - pos_tills - price_tags - product_ranges - products - promotions - purchase_orders - receiving - reporting - revision_sessions - revisions - roles - shopper_tags - shoppers - store_product_inventory_counts - store_product_lots - store_product_rules - store_product_tag_templates - store_snap_incentive_program_coupons - store_vendor_merge_requests - store_vendor_product_merge_requests - store_vendor_products - store_vendors - stores - tag_printings - tag_template_presets - tag_templates - tax_rates - users - variable_weights - vendor_merge_requests - vendor_product_merge_requests - vendors - wallet_payments - wic_products securitySchemes: bearer: type: http scheme: bearer ```` ## Related topics - [Create or fund a gift card](/api-reference/gift-cards/create-or-fund-a-gift-card.md) - [List gift card transactions](/api-reference/gift-cards/list-gift-card-transactions.md) - [The gift card transaction object](/api/gift-cards/transaction.md)