> ## 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 or fund a gift card > Funds a shopper's gift card, creating one if the shopper has none yet, and adjusts its balance. ## OpenAPI ````yaml /api/openapi.json post /v1/gift-cards 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: post: tags: - Gift cards summary: Create or fund a gift card description: >- Funds a shopper's gift card, creating one if the shopper has none yet, and adjusts its balance. operationId: createGiftCard parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGiftCardRequest' responses: '201': description: Gift card funded successfully. content: application/json: schema: $ref: '#/components/schemas/GiftCard' '400': description: '' content: application/json: schema: anyOf: - $ref: '#/components/schemas/InvalidEmployeeError' - $ref: '#/components/schemas/InvalidStoreError' - $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/DuplicateBarcodeError' - $ref: '#/components/schemas/MissingGiftCardIdentifierError' '403': description: '' content: application/json: schema: anyOf: - $ref: '#/components/schemas/InsufficientPermissionsError' - $ref: '#/components/schemas/NoBannerAssociationError' security: - bearer: [] components: schemas: CreateGiftCardRequest: type: object properties: account_number: type: string description: >- The account number, typically read from the physical card's magnetic stripe. Note that this should just be the account number, not any additional Track data. nullable: true amount: type: string description: Amount to load onto the gift card. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' description: type: string description: Description to write alongside the funding 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 that funded the gift card, from the transactions resource. Only a register sends one. physical_barcode: type: string description: >- Barcode on the physical gift card. Provide this, `recipient_phone_number`, or `account_number`. nullable: true purchaser_phone_number: type: string description: >- Phone number of the Shopper that funded the gift card. This may be the same as `recipient_phone_number` if a shopper buys a gift card for themselves. format: phone pattern: ^\+[1-9]\d{1,14}$ recipient_phone_number: type: string description: >- Phone number of the shopper who will own this gift card. This shopper receives messages about this and future transactions. Provide this, `physical_barcode`, or `account_number`. nullable: true format: phone pattern: ^\+[1-9]\d{1,14}$ store_id: type: string description: >- ID of the store the funding belongs to. Optional: name a store to attribute it to, or omit it for funding not tied to a store. pattern: ^[0-9]+$ required: - amount - idempotency_key GiftCard: type: object properties: id: type: string description: Unique identifier for the record. balance: type: string description: Current balance on the gift card. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ barcodes: description: >- Barcodes on the physical cards backing this gift card, across the card and any cards merged into it. type: array items: type: string created_at: type: string description: When the record was created. format: date-time deactivated_at: type: string nullable: true description: When the gift card was deactivated, or null when it is active. format: date-time deactivated_by_api_client_id: type: string nullable: true description: >- ID of the API credential that deactivated the gift card, or null when it is active or was deactivated by a person. deactivated_by_employee_id: type: string nullable: true description: >- ID of the employee who deactivated the gift card, or null when it is active or was deactivated by another actor. deactivated_by_user_id: type: string nullable: true description: >- ID of the back-office user who deactivated the gift card, or null when it is active or was deactivated by another actor. deactivation_reason: type: string nullable: true description: >- Reason recorded when the gift card was deactivated, or null when it is active. last_order_at: type: string nullable: true description: >- When the gift card was last used in a sale or refund, or null when it has not been used yet. format: date-time magstripe_account_numbers: description: >- Account numbers encoded on the magnetic stripe of the physical cards. type: array items: type: string owner_id: type: string nullable: true description: >- ID of the shopper who owns the gift card, or null when it has no owner. printed_account_numbers: description: Account numbers printed on the physical cards. type: array items: type: string purchaser_id: type: string nullable: true description: ID of the shopper who purchased the gift card, or null when unknown. shopper_facing_id: type: string description: >- Short human-readable ID for the gift card, shown to shoppers on receipts and messages. status: description: >- Whether the gift card is active and can be used, or has been deactivated. allOf: - $ref: '#/components/schemas/GiftCardStatus' updated_at: type: string description: When the record was last changed. format: date-time description: >- A prepaid balance a shopper spends at the register. It can be digital, tied to a shopper, or backed by one or more physical cards. A gift card belongs to the banner rather than to any one store, and can be sold, redeemed, or reloaded at any of its registers. required: - id - balance - barcodes - created_at - deactivated_at - deactivated_by_api_client_id - deactivated_by_employee_id - deactivated_by_user_id - deactivation_reason - last_order_at - magstripe_account_numbers - owner_id - printed_account_numbers - purchaser_id - shopper_facing_id - status - updated_at 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 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 DuplicateBarcodeError: type: object properties: barcode: type: string error_code: type: string enum: - duplicate_barcode gift_card_id: type: string required: - barcode - error_code - gift_card_id MissingGiftCardIdentifierError: type: object properties: error_code: type: string enum: - missing_gift_card_identifier 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 GiftCardStatus: type: string enum: - active - deactivated 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 a gift card transaction](/api-reference/gift-cards/create-a-gift-card-transaction.md) - [Sell, Redeem, and Top Up Gift Cards on the POS](/point-of-sale-pos/vori-store-gift-cards/sell-redeem-and-top-up-gift-cards-on-the-pos.md) - [Sell and Manage Blackhawk Gift Cards in Vori POS](/point-of-sale-pos/blackhawk-gift-cards-checks-lottery-and-payouts/sell-and-manage-blackhawk-gift-cards-in-vori-pos.md)