> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Transactions Batch Job

> Retrieve payment, reward, and refund history for up to 1,000 orders in a single asynchronous batch call.

## Order Transactions Batch Job

Retrieve the full transaction history (payments, rewards, refunds) for up to **1,000 orders** in a single call. The job runs asynchronously — this endpoint returns a `jobId` immediately. Poll [Check Batch Status](/api-reference/batches/batch-management/check-status) to get the results.

For a single order, use [Order Transactions](/api-reference/order/order-transactions) instead.

<Info>
  **Security:** Requires **apiKey** and **secretKey** headers. The secret key is required on v4.1; on v4.0 it is required when High Security Mode is enabled.
</Info>

### Poll result shape

When the job completes, the batch status `response` includes `successful` and `failed` arrays. Every submitted order ID appears in one of them — no ID is silently dropped.

| Field                       | Description                                                            |
| --------------------------- | ---------------------------------------------------------------------- |
| `successful[].orderId`      | Order ID that was found                                                |
| `successful[].transactions` | Payment, refund, and reward entries for that order                     |
| `successful[].count`        | Number of transactions returned                                        |
| `failed[].customerId`       | Order ID that failed (field name mirrors other batch failure payloads) |
| `failed[].message`          | Failure reason (e.g. `Order Not Found`)                                |

`transactionType` values in this batch response include `Payment`, `Refund`, and `PartialRefund`.

<Note>
  If a `PaymentReward` record does not exist for an order, a synthetic `Payment` entry is returned so the order always has at least one transaction. Refunds appear as separate `Refund` or `PartialRefund` entries alongside the original `Payment` entry.
</Note>


## OpenAPI

````yaml POST /api/v4.0/integrations/batch/orders/transactions
openapi: 3.1.0
info:
  title: Gameball API
  description: >-
    Gameball REST API v4.0 - Complete API reference for integrating loyalty,
    gamification, and customer engagement features
  version: 4.0.0
servers:
  - url: https://api.gameball.co
security:
  - bearerAuth: []
paths:
  /api/v4.0/integrations/batch/orders/transactions:
    post:
      tags:
        - Batches
      summary: Order Transactions Batch Job
      description: >-
        Retrieve the full transaction history (payments, rewards, refunds) for
        up to 1,000 orders in a single call. The job runs asynchronously — the
        endpoint returns a `jobId` immediately. Poll the batch status endpoint
        to retrieve results.


        **Security:** Requires `apiKey` and `secretKey` headers (secret key
        required on v4.1; on v4.0 required when High Security Mode is enabled).
      operationId: batchOrderTransactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - body
              properties:
                body:
                  type: array
                  description: Order IDs to retrieve. Min 1, max 1,000 items.
                  minItems: 1
                  maxItems: 1000
                  items:
                    type: string
                  example:
                    - ORDER-001
                    - ORDER-002
                    - ORDER-003
            examples:
              sample:
                summary: Sample request
                value:
                  body:
                    - ORDER-001
                    - ORDER-002
                    - ORDER-003
      responses:
        '200':
          description: Batch order transactions job initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: number
                    description: >-
                      The assigned job ID, which is later used for status
                      verification and response retrieval.
                    example: 1748392
      security:
        - apiKey: []
          secretKey: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: apiKey
      in: header
      name: apikey
    secretKey:
      type: apiKey
      in: header
      name: secretkey

````