> ## Documentation Index > Fetch the complete documentation index at: https://docs.smartsend.io/llms.txt > Use this file to discover all available pages before exploring further. # List batches > Returns a paginated list of batch bookings, sorted by most recent first. ## OpenAPI ````yaml /openapi-v2beta.json get /team/{team}/booking-batches openapi: 3.1.0 info: title: Smart Send API description: >- Unified API for shipping operations including service points, routing, and rates. ## Localization The API performs language negotiation to determine the most suitable language for translatable content (such as service names, tracking descriptions, and error messages). The negotiation considers: 1. The `Accept-Language` request header (if provided) 2. The team's configured default language 3. English as the ultimate fallback The resolved language is used for all translatable strings in the response. ## Idempotency Write operations support **idempotency keys** so you can safely retry a request after a network error, timeout, or uncertain outcome without risking a duplicate side effect such as booking the same shipment twice. Idempotency is opt-in: include an `Idempotency-Key` header on a write request (`POST` or `DELETE`) to enable it. Requests sent without the header are not deduplicated. The key is a client-generated string of 16–128 characters (letters, digits, `.`, `_`, `-`) and is compared as-is, so it is case-sensitive. When a key is reused with an identical payload within 24 hours, the API returns the original response (status code and body) without re-executing the operation and sets the `Idempotency-Replayed: true` response header. Reusing a key with a different payload returns `422 Unprocessable Entity`. If the original request is still being processed, the retry returns `409 Conflict` with a `Retry-After` header indicating when to try again. Keys are scoped per client and expire automatically after the 24-hour window. See the [idempotency guide](https://docs.smartsend.io/api-reference/idempotency) for requirements and examples. ## User-Agent We recommend including a descriptive `User-Agent` header with every request, following the `Product/Version (Comments)` pattern from [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3). A good User-Agent helps us identify your integration and speeds up debugging when you contact support. Example: `smart-send-logistics/8.1.0 (WooCommerce/8.5.0; WordPress/6.4.2; PHP/8.1)` ## Request-ID We recommend including a unique `Request-ID` header with every request. The value is echoed back in the response and included in internal logs, making it possible to correlate logs from your implementation with logs in Smart Send. This is especially useful when contacting support about a specific request. version: 2.0.0-beta contact: name: Smart Send url: https://www.smartsend.io servers: - url: https://app.smartsend.io/api/v2 description: Production security: - bearerAuth: [] - oauth2: [] tags: - name: Teams description: Teams available to the authenticated user - name: Service Points description: Pickup points and delivery locations - name: Routing description: Reference data (carriers, services, addons) and route availability - name: Rates description: Shipping rates and pricing for specific shipments - name: Tracking description: Shipment tracking information and event history - name: Shipments description: Create and manage shipments - name: Booking description: Booking of shipments externalDocs: description: Booking documentation url: https://docs.smartsend.io/features/booking - name: Booking batches description: |- Batch operations for booking multiple shipments asynchronously. Processing operates after the _first-in-first-out_ principle. externalDocs: description: Batch booking documentation url: https://docs.smartsend.io/features/booking#batch-booking paths: /team/{team}/booking-batches: get: tags: - Booking batches summary: List batches description: Returns a paginated list of batch bookings, sorted by most recent first. operationId: listBatches parameters: - $ref: '#/components/parameters/team' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Request-ID' - name: state in: query required: false schema: $ref: '#/components/schemas/BatchState' description: Filter by batch state - name: page in: query required: false schema: type: integer default: 1 minimum: 1 description: Page number for pagination - name: per_page in: query required: false schema: type: integer default: 100 minimum: 1 maximum: 1000 description: Number of batches per page responses: '200': description: Batches retrieved successfully headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/Batch' meta: $ref: '#/components/schemas/PagePaginationMeta' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerAuth: [] - oauth2: - shipment:read components: parameters: team: name: team in: path required: true schema: type: string minLength: 1 examples: - ad9546c1-393e-49a5-9a72-5cc146c9bec5 description: Team identifier. All resources are scoped to this team. Accept-Language: name: Accept-Language in: header required: false schema: type: string default: en examples: - da-DK, da;q=0.9, en;q=0.8 description: >- Preferred language(s) for translatable content using BCP 47 language tags. Supports quality values (q-factors) for priority ordering. The API negotiates the best available language based on this header, the team's configured language, and available translations. If omitted, the team's default language is used. Request-ID: name: Request-ID in: header required: false schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._-]{1,128}$ description: >- Any value passed in this request will be returned in the same header. This can be used to correlate requests between client and server. examples: uuid: summary: UUID v4 value: 3f5d9a8e-8e6f-4d9b-9d9c-9c6b3db2d1a0 opaque: summary: Opaque client-generated key value: booking-12345-at-1768609378 schemas: BatchState: type: string description: Current state of the batch booking enum: - open - queued - processing - completed - failed Batch: type: object description: A batch of shipments for bulk booking properties: uuid: type: - 'null' - string format: uuid readOnly: true description: Unique identifier for the batch examples: - 550e8400-e29b-41d4-a716-446655440001 state: readOnly: true description: Current state of the batch anyOf: - type: 'null' - allOf: - $ref: '#/components/schemas/BatchState' reference: type: - 'null' - string description: Human-readable reference visible to the user identifier: type: - 'null' - string description: System identifier for internal integrations total_count: type: - 'null' - integer readOnly: true description: Total number of shipments in the batch examples: - 100 completed_count: type: - 'null' - integer readOnly: true description: Number of successfully booked shipments examples: - 45 failed_count: type: - 'null' - integer readOnly: true description: Number of failed shipments examples: - 2 progress: type: - 'null' - integer minimum: 0 maximum: 100 readOnly: true description: Percentage of shipments processed (0-100) examples: - 47 created_at: type: - 'null' - string format: date-time readOnly: true description: When the batch was created started_at: type: - 'null' - string format: date-time readOnly: true description: When the batch processing was initiated finished_at: type: - 'null' - string format: date-time readOnly: true description: When the batch finished processing required: - uuid - state - reference - identifier - total_count - completed_count - failed_count - progress - created_at - started_at - finished_at PagePaginationMeta: type: object required: - current_page - per_page - total - last_page - from - to properties: current_page: type: integer description: Current page number examples: - 1 per_page: type: integer description: Number of items per page examples: - 100 total: type: integer description: Total number of items across all pages examples: - 2500 last_page: type: integer description: Last page number examples: - 25 from: type: - 'null' - integer description: Index of first item on current page (1-based) examples: - 1 to: type: - 'null' - integer description: Index of last item on current page (1-based) examples: - 100 ErrorResponse: type: object required: - message properties: message: type: string description: Human-readable error message examples: - Something unexpected happened. RateLimitErrorResponse: type: object required: - message properties: message: type: string description: Human-readable error message indicating rate limit exceeded headers: Correlation-ID: description: >- Unique identifier for the request, useful for debugging and support. The id is automatically assigned to each request and can helps trace the request in system logs. Provide this value in case of any errors helps debugging. schema: type: string format: uuid examples: - 550e8400-e29b-41d4-a716-446655440000 Request-ID: description: >- If the request contained a `Request-ID` then the same value is returned as the `Request-ID`. This can be used to correlate requests between client and server. schema: type: string Retry-After: description: Number of seconds to wait before retrying the request. schema: type: integer examples: - 30 responses: Unauthorized: description: Authentication credentials were missing or invalid headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: The authenticated user does not have permission to perform this action headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' TooManyRequests: description: Rate limit exceeded. Wait before retrying. headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' InternalServerError: description: An unexpected error occurred on the server headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServiceUnavailable: description: The service is temporarily unavailable. Please try again later. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer oauth2: type: oauth2 description: OAuth 2.0 Authorization Code flow for API access flows: authorizationCode: authorizationUrl: https://app.smartsend.io/oauth/authorize tokenUrl: https://app.smartsend.io/oauth/token scopes: service_points: Access service points and pickup locations routing: Access routing information (carriers, services, addons, routes) tracking:read: Access shipment tracking information rates:read: Get shipping rates and pricing shipment:read: Read shipment information shipment:write: Create and manage shipments ````