API
GuidesWhat’s newGet API token
Async Batch

Async batch Tasks

Most commonly, the response from listing tasks on an async_batch id will be identical to the body of a singular request to standard Recharge API endpoints. However, in some instances there are variations from the standard list task response body. See below for examples corresponding to each batch_type.

Related guides: Examples of async batches

10 additions in V2, marked New

Everything marked New also works when you send X-Recharge-Version: 2021-11.

Endpoints

#The async batch Tasks object

Attributes

  • batch_idinteger
    Indicates the batch that the task is contained by
  • bodyobject
    This object contains the body of a standard API request. For example, when creating discounts with a discount_create batch, this parameter contains a standard body for POST /discounts
  • completed_atdatetime
    Indicates the date and time a task was completed
  • stalled_atdatetime · nullableNew
    Indicates the date and time a task was flagged as stalled during processing.
  • created_atdatetime
    Indicates the date and time that a task was created and added to the batch
  • deleted_atdatetime
    Indicates the date and time that a task was deleted from the batch
  • idinteger
    Unique identifier for the task within a batch
  • queued_atdatetime
    Indicates the date and time a task was queued for processing within batch processing
  • resultobject
    Contains the individual response body for the task
  • started_atdatetime
    Indicates the date and time a task was processed
  • statusstring
    Indicates the status of the task within a batch.
    Possible values
    pendingqueuedprocessingsuccessfail
  • updated_atdatetime
    Indicates the date and time a task was most recently updated

#Create a batch task

POST/async_batches/{batch_id}/tasks
A batch contains operations of similar type (indicated by batch_type), called tasks. A task is typically representative of a single API request, with a body parameter containing the standard request body for the associated batch_type. A single request to add tasks may contain up to 1,000 tasks, and a batch may contain up to 10,000 tasks.

##HTTP examples

POST /async_batches/<batch_id>/tasks
Scopewrite_batches
Batches will only leverage resources from the same version they are created in. e.g. a batch created with V2 will only process tasks from the V2 version.

Returns 201 with {"count": <number of tasks added>}. Tasks can only be added while the batch has status not_started, and the token also needs the write scope of the resource the batch type operates on.

Body parameters

  • tasksarray of objectsRequiredNew
    List of tasks to add to the batch. A single request can contain at most 1,000 tasks and a batch can hold at most 10,000 tasks.
    Show child attributesHide child attributes11 new
    • bodyobjectRequiredNew
      The body of the task, in the format required by the batch_type of the batch.

Response attributes

  • idstring
    Unique identifier of the batch, used for adding tasks to a batch and to initiate batch processing
  • batch_typestring
    Indicates the object type and operation required for all tasks in a batch
    Possible values
    discount_creatediscount_updatediscount_deletebulk_plans_createbulk_plans_updatebulk_plans_deleteonetime_createonetime_delete
  • closed_atstring
    Indicates the date and time that processing was completed for a batch
  • created_atstring
    Indicates the date and time a batch was created
  • fail_task_countstring
    Indicates the number of failed tasks in a batch, during or after processing
  • statusstring
    Indicates the status of the batch. Available statuses are not_started, processing, completed, failed
  • submitted_atstring
    Indicates the date and time that a batch was triggered to process
  • success_task_countstring
    Indicates the number of successful tasks in a batch, during or after processing.
  • total_task_countstring
    Indicates the total number of tasks in a batch
  • updated_atstring
    Indicates the date and time at which a batch was last updated
  • versionstring
    Indicates the API version of the batch.
    read-only field
POST/async_batches/{batch_id}/tasks
curl -X POST 'https://api.rechargeapps.com/async_batches/21/tasks' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "tasks": [
    {
      "body": {
        "code": "indexing",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "maroon",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "web services",
        "value": 100,
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled"
      }
    },
    {
      "body": {
        "code": "PCI",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "Cheese",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "overriding",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "bandwidth-monitored",
        "value": 100,
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled"
      }
    },
    {
      "body": {
        "code": "Falkland Islands (Malvinas)",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "Computer",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "digital",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    }
  ]
}'
Response
{
  "count": 10
}

#List batch tasks

GET/async_batches/{batch_id}/tasks
Returns a list of all tasks in the indicated batch, using batch id. For batches with many tasks, pagination is supported when listing tasks. Use this function to evaluate the task-level results of a batch during, or after processing. Task results will be contained in the results object of each task.
Scoperead_batches
The response includes next_cursor and previous_cursor, except when the ids filter is used.

Query parameters

  • idsstring
    Filter tasks by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error
  • statusstringNew
    Filter tasks by status.
    Possible values
    pendingqueuedprocessingsuccessfail
  • completedbooleanNew
    When true, return only tasks that have finished processing; when false, return only tasks that have not finished.
  • sort_bystringNew
    Sort order of the results. Defaults to id-desc.
    Possible values
    id-ascid-desc
  • limitintegerNew
    Number of results to return. Defaults to 50; the maximum is 250.
  • pageintegerNew
    Page to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.
  • cursorstringNew
    Return either the next or previous page of tasks using the next_cursor or previous_cursor value from a previous response. When cursor is passed, only limit may be passed with it.
GET/async_batches/{batch_id}/tasks
curl 'https://api.rechargeapps.com/async_batches/16/tasks' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'
Response
{
  "next_cursor": null,
  "previous_cursor": null,
  "async_batch_tasks": [
    {
      "id": 1490831511,
      "batch_id": 765278,
      "body": {
        "code": "Computer",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    },
    {
      "id": 1490831510,
      "batch_id": 765278,
      "body": {
        "code": "Falkland Islands (Malvinas)",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    },
    {
      "id": 1490831509,
      "batch_id": 765278,
      "body": {
        "code": "bandwidth-monitored",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    },
    {
      "id": 1490831508,
      "batch_id": 765278,
      "body": {
        "code": "overriding",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    },
    {
      "id": 1490831507,
      "batch_id": 765278,
      "body": {
        "code": "Cheese",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    },
    {
      "id": 1490831506,
      "batch_id": 765278,
      "body": {
        "code": "PCI",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    },
    {
      "id": 1490831505,
      "batch_id": 765278,
      "body": {
        "code": "web services",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    },
    {
      "id": 1490831504,
      "batch_id": 765278,
      "body": {
        "code": "maroon",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    },
    {
      "id": 1490831503,
      "batch_id": 765278,
      "body": {
        "code": "indexing",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      },
      "completed_at": null,
      "created_at": "2022-02-17T06:40:53+00:00",
      "deleted_at": null,
      "queued_at": null,
      "result": null,
      "stalled_at": null,
      "started_at": null,
      "status": "pending",
      "updated_at": "2022-02-17T06:40:53+00:00"
    }
  ]
}

#Retrieve a batch taskNew

GET/async_batches/{batch_id}/tasks/{task_id}
Retrieves a single task of a batch by its id.
Scoperead_batches
GET/async_batches/{batch_id}/tasks/{task_id}
curl 'https://api.rechargeapps.com/async_batches/176190/tasks/170629' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "async_batch_task": {
    "id": 4058301,
    "batch_id": 31250,
    "body": {
      "discount_id": 88012
    },
    "status": "pending",
    "result": null,
    "queued_at": null,
    "started_at": null,
    "stalled_at": null,
    "completed_at": null,
    "deleted_at": null,
    "created_at": "2026-09-14T10:01:40",
    "updated_at": "2026-09-14T10:01:40"
  }
}