> ## Documentation Index > Fetch the complete documentation index at: https://docs.gate.com/llms.txt > Use this file to discover all available pages before exploring further. # Batch Query Gift Cards > Returns a paginated list of gift cards created by the current merchant, filtered by batch ID or creation time range. When both filters are provided, the API returns their intersection. ## Overview This page documents the `POST /v1/pay/gift/batch/query` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * Filter by batch ID, creation time range, or both. When both are provided, both filters apply. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). ## OpenAPI ````yaml global/api-reference/version/100/en/openapi/gift-card-openapi.json POST /v1/pay/gift/batch/query openapi: 3.1.0 info: title: GatePay API description: >- The gift card API solution provided by Gate Pay is designed to facilitate the instant creation and value checking of gift cards. license: name: MIT version: 1.0.0 servers: - url: https://openplatform.gateapi.io security: [] paths: /v1/pay/gift/batch/query: post: summary: Batch query gift cards description: >- Returns a paginated list of gift cards created by the current merchant, filtered by batch ID or creation time range. When both filters are provided, the API returns their intersection. parameters: - $ref: '#/components/parameters/X-GatePay-Certificate-ClientId' - $ref: '#/components/parameters/X-GatePay-Signature' - $ref: '#/components/parameters/X-GatePay-Timestamp' - $ref: '#/components/parameters/X-GatePay-Nonce' requestBody: description: >- Batch query parameters. Provide batch_id or a complete start_time/end_time range. content: application/json: schema: $ref: '#/components/schemas/GiftCardBatchQueryRequest' examples: batchAndTimeExample: summary: Filter by batch ID and creation time value: batch_id: G545273793309741056 start_time: 1791916618083 end_time: 1791939618083 page: 1 page_size: 20 required: true responses: '200': description: Query successful content: application/json: schema: $ref: '#/components/schemas/GiftCardBatchQueryResponse' examples: successResponse: summary: Successful response value: status: SUCCESS code: '000000' errorMessage: '' data: total: 1 has_more: false list: - batch_id: G545273793309741056 card_num: '5607423016280059' key: EXAMPLE-REDEEM-CODE title: Festival Gift Card creator_name: GateUser-8118f6f8 amount: '0.99' status: '3' currency: USDT card_temp_id: '346749173549240320' create_time: 1791920000000 exchange_uid: 39992131 exchange_time: 1791923600000 components: parameters: X-GatePay-Certificate-ClientId: name: X-GatePay-Certificate-ClientId in: header required: true description: Merchant client ID schema: type: string example: mZ96D37oKk-HrWJc X-GatePay-Signature: name: X-GatePay-Signature in: header required: true description: Signature schema: type: string example: >- b8c4705ff4c1357f2a27925dd180c1e1f4a244148f312a2dee5afbcc6f4b150e9ffceee455c5a298f895d43a64ee829eebdfd262539d45c41f7aee4336fd8c8c X-GatePay-Timestamp: name: X-GatePay-Timestamp in: header required: true description: >- Millisecond timestamp; the difference from server time must not exceed 30 seconds. schema: type: string example: '1738934053475' X-GatePay-Nonce: name: X-GatePay-Nonce in: header required: true description: Nonce schema: type: string example: '5417061546' schemas: GiftCardBatchQueryRequest: type: object description: Provide batch_id or a complete start_time/end_time range. dependentRequired: start_time: - end_time end_time: - start_time anyOf: - required: - batch_id - required: - start_time - end_time properties: batch_id: type: string minLength: 1 maxLength: 64 description: >- Gift card batch ID. The API uses an exact match. When combined with a time range, both filters apply. example: G545273793309741056 start_time: type: integer format: int64 minimum: 0 description: >- Inclusive creation time range start as a Unix timestamp in milliseconds. Must be provided with end_time. example: 1791916618083 end_time: type: integer format: int64 minimum: 0 description: >- Inclusive creation time range end as a Unix timestamp in milliseconds. A single query cannot span more than 31 days. example: 1791939618083 page: type: integer minimum: 1 default: 1 description: Page number starting from 1. example: 1 page_size: type: integer minimum: 1 maximum: 100 default: 20 description: >- Number of records per page. The default is 20 and the maximum is 100. example: 20 GiftCardBatchQueryResponse: type: object properties: status: type: string description: Response status example: SUCCESS code: type: string description: Response code. 000000 indicates success. example: '000000' errorMessage: type: string description: Error message. Empty on success. example: '' data: $ref: '#/components/schemas/GiftCardBatchQueryData' GiftCardBatchQueryData: type: object properties: total: type: integer format: int64 description: Total number of matching records example: 1 has_more: type: boolean description: >- Whether another page is available. When true, query page+1 to continue. example: false list: type: array description: Gift cards on the current page items: $ref: '#/components/schemas/GiftCardBatchQueryItem' GiftCardBatchQueryItem: type: object properties: batch_id: type: string description: Gift card batch ID example: G545273793309741056 card_num: type: string description: Gift card number example: '5607423016280059' key: type: string description: Redemption code example: EXAMPLE-REDEEM-CODE title: type: string description: Gift card title example: Festival Gift Card creator_name: type: string description: Gift card creator name example: GateUser-8118f6f8 amount: type: string description: Gift card amount example: '0.99' status: type: string description: >- Gift card status: 0=unknown, 1=pending payment, 2=not redeemed, 3=redeemed, 4=frozen, 5=payment failed, 6=manual review, 7=review rejected, 8=review payment failed enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' example: '3' currency: type: string description: Gift card currency example: USDT card_temp_id: type: string description: Gift card cover ID example: '346749173549240320' create_time: type: integer format: int64 description: Creation time as a Unix timestamp in milliseconds example: 1791920000000 exchange_uid: type: integer format: int64 description: Redeemer ID example: 39992131 exchange_time: type: integer format: int64 nullable: true description: >- Redemption time as a Unix timestamp in milliseconds. Null if the card has not been redeemed. example: 1791923600000 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.