Batch processing for reward claims across many customers and for adding or removing customers from lists, each returning a batch id with status and error reporting endpoints.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/antavo-bulk-operations-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.0.0
info:
contact: {}
title: Antavo Bulk Operations API
version: 1.0.0
servers:
- url: https://api.staging.antavo.com
description: The Antavo staging environment
paths:
/v1/bulk-operation/coupons/{batch_id}/status/error:
get:
tags:
- Coupons
summary: Query the list of errors related to a coupon import
description: This endpoint allows you to query information about any errors or issues encountered
during a coupon import. It provides details about failures that may have occurred during the process.
parameters:
- in: path
name: batch_id
required: true
example: batch001
description: The batch ID associated with the coupon import operation.
schema:
type: string
responses:
'200':
description: Returned after the coupon import operation has been processed. Provides information
about errors, if any, that occurred during the operation.
content:
application/json:
schema:
$ref: '#/components/schemas/CouponsStatusResponse'
examples:
Errors were found:
description: Returned if errors were found during the processing of the batch.
value:
status: success
metadata:
pagination:
total: 42
next: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status/error?offset=40&limit=20
previous: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status/error?offset=0&limit=20
payload:
number_of_errors: 42
coupons:
- coupon_code: CODE1
pool_id: 146cb226c3d47e4d6a28176b
error_message: Error message
error_code: 123456
- coupon_code: CODE2
pool_id: 146cb226c3d47e4d6a28176b
error_message: Error message
error_code: 123456
- '...'
No errors were found:
description: Returned if no errors were found during the processing of the batch.
value:
status: success
metadata:
pagination:
total: 0
payload:
number_of_errors: 0
coupons: {}
'404':
description: The batch ID provided as a parameter does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
examples:
Bulk operation request queue is not found:
value:
status: error
error:
type: NotFoundException
code: 320504
message: Bulk operation request queue is not found
/v1/bulk-operation/coupons/{batch_id}/status:
get:
tags:
- Coupons
summary: Query the status of a coupon import
description: This endpoint allows you to query the status of a coupon batch import. It provides
information about the current processing status of the operation, which can be `queued`, `processing`
or `done`.
parameters:
- in: path
name: batch_id
required: true
example: batch001
description: The batch ID associated with the coupon import operation.
schema:
type: string
responses:
'200':
description: 'Returned after the batch has been successfully added to the queue.
Provides information about the batch status, including whether it is `queued`, `processing`,
or `done`.'
content:
application/json:
schema:
$ref: '#/components/schemas/CouponsStatusResponse'
examples:
Batch status - queued:
description: Returned if the batch is queued for processing
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 0
url: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status
payload:
batch_status: queued
number_of_coupons: 0
Batch status - processing:
description: Returned if the batch is currently being processed
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 0
url: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status
payload:
batch_status: processing
number_of_coupons: 0
Batch status - done:
description: Returned if the batch has been processed and the results are available
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 60
url: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status
payload:
batch_status: done
number_of_coupons: 1000
'404':
description: The batch ID provided as a path parameter does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ListBatchNotFound'
examples:
Batch ID is not found:
value:
status: error
error:
type: NotFoundException
code: 202004
message: Batch ID is not found
/v1/bulk-operation/customer-list/{batch_id}/status/errors:
get:
tags:
- Customer lists
summary: Query the erronous list operation attempts
description: This endpoint allows you to query information about any errors or issues encountered
during a list operation process. It provides details about errors, if any, that occurred during
the operation.
parameters:
- in: path
name: batch_id
required: true
example: batch001
description: The external batch ID associated with the list operation.
schema:
type: string
- name: offset
in: query
description: 'Offsets the starting number of errors to return. This is used in pagination in conjunction
with the limit query.
'
schema:
type: integer
example: 10
default: 0
- name: limit
in: query
description: 'Limits the number of errors to be returned in one response. Other values are accessible
by pagination made accessible via the offset.
'
schema:
type: integer
example: 50
default: 100
responses:
'200':
description: Returned after the list operation request has been processed. Provides information
about errors, if any, that occurred during the operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ListErrorResponse'
examples:
Errors listed:
value:
status: success
metadata:
pagination:
total: 42
next: https://api.{environment}.antavo.com/customer-list/batch001/status/error?offset=40&limit=20
previous: https://api.{environment}.antavo.com/customer-list/batch001/status/error?offset=0&limit=20
payload:
number of errors: 42
customers:
customer_01:
customer_list: {}
error message: {}
error code: {}
No errors:
value:
status: success
metadata:
pagination:
total: 0
payload:
number_of_errors: 0
customers: {}
'404':
description: The batch ID provided as a parameter does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
/v1/bulk-operation/customer-list/{batch_id}/status:
get:
tags:
- Customer lists
summary: Query the status of a list operation process
description: This endpoint allows you to query the status of a list operation process, such as adding
or removing customers from a customer list. It provides information about the current processing
status of the operation.
parameters:
- in: path
name: batch_id
required: true
example: batch001
description: The external batch ID associated with the list operation.
schema:
type: string
responses:
'200':
description: 'Returned after the batch has been successfully added to the queue.
Provides information about the batch status, including whether it is `queued`, `processing`,
or `done`.'
content:
application/json:
schema:
$ref: '#/components/schemas/ListStatusResponse'
examples:
Batch status - queued:
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 0
url: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error
payload:
batch_status: queued
number_of_customers: 0
Batch status - processing:
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 0
url: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error
payload:
batch_status: processing
number_of_customers: 0
Batch status - done:
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 60
url: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error
payload:
batch_status: done
number_of_customers: 1000
'404':
description: The batch ID provided as a path parameter does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ListBatchNotFound'
/v1/bulk-operation/reward/claim/{batch_id}/status/error:
get:
tags:
- Rewards
summary: Query the failed reward claim attempts
description: This endpoint returns the error occured while processing the batch.
parameters:
- in: path
name: batch_id
description: The ID of the batch.
required: true
schema:
type: string
example: batch001
- name: offset
in: query
description: 'Offsets the starting number of errors to return. This is used in pagination in conjunction
with the limit query.
'
schema:
type: integer
example: 10
default: 0
- name: limit
in: query
description: 'Limits the number of errors to be returned in one response. Other values are accessible
by pagination made accessible via the offset.
'
schema:
type: integer
example: 50
default: 100
responses:
'200':
description: Returned after the batch claim request has been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The batch ID provided as parameter does not exists.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchNotFound'
deprecated: false
/v1/bulk-operation/reward/claim/{batch_id}/status:
get:
tags:
- Rewards
summary: Query the status of the reward claim process
description: This API endpoint allows you to query the status of a bulk reward claim process, providing
details on the processing status, any errors encountered, and the overall completion status.
parameters:
- in: path
name: batch_id
description: The ID of the batch.
required: true
schema:
type: string
example: batch001
responses:
'200':
description: Returned after the batch has been successfully added to the queue.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
examples:
Batch status - queued:
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 0
url: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error
pagination:
total: 0
payload:
batch_status: queued
customers: []
Batch status - processing:
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 0
url: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error
pagination:
total: 0
payload:
batch_status: processing
customers: []
Batch status - done:
value:
status: success
metadata:
bulk_operation_error:
number_of_errors: 60
url: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error
pagination:
total: 60
next: https://api.{environment}.antavo.com}/v1/bulk-operation/reward/claim/batch001/status?offset=40&limit=20
previous: https://api.{environment}.antavo.com}/v1/bulk-operation/reward/claim/batch001/status?offset=0&limit=20
payload:
batch_status: done
customers:
- claimed_at: 2023-07-25T15:15:16+01:0
code: 318-ogj-393
created_at: 2023-07-25T15:15:16+01:0
reward_id: 6275010c75c54b7810090000
id: 63dcb791eb80ef351838fdfb:318-ogj-393
type: gift_card
value: 100
customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
batch_id: batch001
status: claimed
custom_attributes:
country: DE
purchase_treshold: 100
campaign: 23F/W
'404':
description: The batch ID provided as parameter does not exists.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchNotFound'
deprecated: false
/v1/bulk-operation/coupons/{coupon_pool_id}/{action}:
post:
tags:
- Coupons
summary: Manage coupon codes in coupon pools
description: 'This endpoint allows you to upload, assign, and unassign coupons in Coupon Pools in
batches. It supports both pre-assigned and unassigned coupons. Uploaded coupon batches are processed
asynchronously.
Each request can process up to 50,000 coupon codes.'
parameters:
- name: coupon_pool_id
in: path
description: The ID of an existing coupon pool for which the source is set to `uploaded`.
required: true
schema:
type: string
example: 146cb226c3d47e4d6a28176b
- name: action
in: path
description: The action carried on the coupons, which can be `add`, `assign`, or `unassign`.
required: true
schema:
type: string
example: add
requestBody:
required: true
description: Request body to import coupons to the specified coupon pool.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AddCouponsRequest'
- $ref: '#/components/schemas/AssignCouponsRequest'
- $ref: '#/components/schemas/UnassignCouponsRequest'
examples:
Add coupons:
summary: Request body for the Add action
value:
coupons:
- CODE1
- CODE2
Assign coupons:
summary: Request body for the Assign action
value:
coupons:
- coupon_code: CODE1
customer_id: 30114810-8340-4144-a193-7699f66d184d
- coupon_code: CODE2
customer_id: e9e5a706-b785-405a-bcf3-2e7859fd59d3
- coupon_code: CODE3
Unassign coupons:
summary: Request body for the Unassign action
value:
coupons:
- coupon_code: CODE1
customer_id: 30114810-8340-4144-a193-7699f66d184d
- coupon_code: CODE2
customer_id: e9e5a706-b785-405a-bcf3-2e7859fd59d3
responses:
'200':
description: 200 OK
content:
application/json:
schema:
$ref: '#/components/schemas/CouponsResponse'
examples:
Success:
value:
status: success
metadata:
external_batch_id: batch_001
payload:
batch_id: batch001
'400':
description: 400 Bad Request Exception
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
examples:
Payload is not found or is empty:
value:
status: error
error:
type: BadRequestException
code: 202002
message: The 'payload' field is not found or empty
Coupon codes exceed the limit:
value:
status: error
error:
type: BadRequestException
code: 202003
message: The list of codes exceeds the size limitation of the endpoint
'404':
description: 404 Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
examples:
Coupon pool not found:
summary: The coupon pool ID provided in the path does not match the ID or external ID
of an existing coupon pool
value:
status: error
error:
type: NotFoundException
code: 202001
message: Coupon Pool not found
/v1/bulk-operation/customer-list/add/{customer_list_id}:
post:
tags:
- Customer lists
summary: Add customers to a customer list
description: 'This API endpoint allows you to add a group of customers to a customer list all at
once.
It accepts a single customer list ID and an array of customer IDs as input.
This API endpoint operates asynchronously, so customer list updates are processed separately.
'
parameters:
- in: path
name: customer_list_id
required: true
description: The ID of the customer list to which customers will be added to.
schema:
type: string
example: 63f2cc942d6ef241c0167e6c
responses:
'200':
description: Successful response with batch details.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccesfulResponse'
'400':
description: Bad request, indicates missing or empty payload or exceeding payload size limitations.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'404':
description: Thrown in case there is no Customer list registered in Antavo with the ID provided
in the path as customerListId.
content:
application/json:
schema:
$ref: '#/components/schemas/ListNotFoundResponseAdd'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerList'
/v1/bulk-operation/customer-list/remove/{customer_list_id}:
post:
tags:
- Customer lists
summary: Remove customers from a customer list
description: 'This endpoint supports the removal of customers from a customer list in batches.
It operates asynchronously, processing customer list updates separately.'
parameters:
- in: path
name: customer_list_id
example: 63f2cc942d6ef241c0167e6c
required: true
description: The ID of the customer list from which customers will be removed.
schema:
type: string
responses:
'200':
description: Success response with batch details.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccesfulResponse'
'400':
description: Bad request, indicates missing or empty payload or exceeding payload size limitations.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'404':
description: Thrown in case there is no Customer list registered in Antavo with the ID provided
in the path as customer_list_id.
content:
application/json:
schema:
$ref: '#/components/schemas/ListNotFoundResponseRemove'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerListRemove'
/v1/bulk-operation/reward/claim/{reward_id}:
post:
tags:
- Rewards
summary: Claim a specific reward to multiple customers
description: 'Submit reward claim requests for a batch of customers. Each request can include a
maximum of 100,000 customers.
Please note that only one bulk reward claim process can run at a time for one specific reward.
If additional batches are submitted while the current one is still processing, they will be added
to the queue and processed once the ongoing batch is completed.
By the end of the process, the reward events get registered in each customer''s event history.'
parameters:
- in: path
name: reward_id
required: true
description: The ID of the reward to be claimed.
schema:
type: string
example: 63dcb7736123782ba6336425
responses:
'200':
description: The batch claim request has been submitted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/response'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseBadRequest'
'404':
description: Reward not found
content:
application/json:
schema:
$ref: '#/components/schemas/RewardNotFound'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkRewardClaim'
components:
securitySchemes:
api_key:
type: apiKey
description: Provides API Key access to the endpoint.
name: api_key
in: query
schemas:
NotFoundErrorResponse:
type: object
properties:
status:
type: string
example: error
description: Status of the request.
error:
type: object
properties:
type:
type: string
example: NotFoundException
description: Type of the error.
code:
type: string
example: 330531
description: Error code.
message:
type: string
example: Batch ID is not found
description: Human-readable error message.
CouponsStatusResponse:
type: object
properties:
status:
type: string
example: success
description: Status of the request.
metadata:
type: object
description: Metadata related to the bulk operation.
properties:
bulk_operation_error:
type: object
description: Any errors encountered during the bulk operation.
properties:
number_of_errors:
type: number
description: The number of encountered errors.
url:
type: string
description: URL to retrieve detailed error information.
payload:
type: object
description: Details of the bulk operation payload.
properties:
batch_status:
type: string
description: The status of the current batch.
number_of_coupons:
type: number
description: The number of processed coupons.
ListBatchNotFound:
type: object
properties:
status:
type: string
example: error
description: Status of the request.
error:
type: object
description: Error details.
properties:
type:
type: string
example: NotFoundException
description: Type of the error.
code:
type: number
example: 330521
description: Error code.
message:
type: string
example: Batch ID is not found
description: Human-readable error message.
ListErrorResponse:
type: object
properties:
status:
type: string
example: success
description: The current status of the process.
metadata:
type: object
description: Metadata related to the bulk operation.
properties:
pagination:
type: object
properties:
total:
type: number
description: Total number of entries.
example: 42
next:
type: string
description: Link to access the next series of entries.
example: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error?offset=40&limit=20
previous:
type: string
description: Link to access the previous series of entries.
example: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error?offset=0&limit=20
payload:
type: object
properties:
number_of_errors:
type: number
example: 42
customers:
type: object
properties:
customer_01:
type: object
properties:
customer list:
type: string
example: null
error_message:
type: string
example: null
error_code:
type: number
example: null
ListStatusResponse:
type: object
properties:
status:
type: string
example: success
description: The current status of the bulk process.
metadata:
type: object
description: Metadata related to the bulk operation.
properties:
bulk_operation_error:
type: object
description: Errors occurred.
properties:
number_of_errors:
description: The number of errors encountered during the process.
type: number
url:
type: string
description: URL to retrieve detailed error information.
pagination:
type: object
properties:
total:
type: number
description: Total number of entries.
next:
type: string
description: Link to access the next series of entries.
previous:
type: string
description: Link to access the previous series of entries.
BatchNotFound:
type: object
properties:
status:
type: string
example: error
description: The status of the error.
error:
type: object
properties:
type:
type: string
description: Type of the error.
example: NotFoundException
code:
type: number
description: Error code.
example: 320510
message:
type: string
description: Human-readable error message.
example: Batch ID is not found
ErrorResponse:
type: object
properties:
status:
type: string
example: success
description: Status of the request.
metadata:
type: object
description: Metadata related to the bulk operation.
properties:
pagination:
type: object
properties:
total:
description: Total number of entries.
type: number
example: 42
next:
description: Link to access the next series of entries.
type: string
example: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error?offset=40&limit=20
previous:
description: Link to access the
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/antavo/refs/heads/main/openapi/antavo-bulk-operations-openapi.yml