Async Batch

Async batch endpoints

The Async batches API can be used for processing large volumes of operations asynchronously, in order to reduce aggregate processing time and network traffic when interacting with many unique objects. For example, a user can leverage async_batches to create 1000 discounts with only 3 API requests.

As shown in the diagram below, the necessary steps to create and process a batch are:

1. Create an async_batch with the desired batch_type

2. Add tasks (individual operations) to your batch. You can add up to 1,000 tasks with each request, up to 10,000 tasks per batch.

3. Submit the batch for processing. Until a batch is submitted for processing, no tasks are attempted.

4. You may retrieve the batch to view progress details while it processes, or register for the async_batch/processed webhook to receive immediate notification of batch completion.

5. Page through the tasks in the batch to view results of each completed or failed task.

Related guides: Examples of Async batches

Endpoints

POST/async_batches
GET/async_batches/{id}
GET/async_batches
POST/async_batches/{batch_id}/process

#The Async batch object

Attributes

batch_typestring
Indicates the object type and operation required for all tasks in a batch
Possible values
address_discount_applyaddress_discount_removediscount_creatediscount_deletediscount_updateproduct_createproduct_updateproduct_deleteonetime_createonetime_deletebulk_subscriptions_createbulk_subscriptions_updatebulk_subscriptions_deletesubscription_cancel
Batches will only leverage resources from the same version they are created in. e.g. a batch created with 2021-11 will only process tasks from the 2021-11 version.
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
idstring
Unique identifier of the batch, used for adding tasks to a batch and to initiate batch 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 date and time at which a batch was last updated

The Async batch object

{
  "async_batch": {
    "id": 19,
    "batch_type": "desired_batch_type",
    "closed_at": null,
    "created_at": "2020-06-05T08:52:10",
    "deleted_at": null,
    "fail_task_count": 0,
    "status": "not_started",
    "submitted_at": null,
    "success_task_count": 0,
    "total_task_count": 0,
    "updated_at": "2020-06-05T08:52:10",
    "expired_at": "2020-07-15T00:00:00"
  }
}

#Create a batch

POST/async_batches

In order to create, retrieve, or process batches, the API token requires the write_batches permission. Additional permissions are required, dependent upon the indicated batch_type. For example, for a batch type of discount_create, the API token requires the write_discounts permission.

Create a new batch, and indicate the desired outcome of the batch using batch_type.

CAUTION - Async batches and their tasks will only be retained in Recharge for one month after batch creation.

Available batch types

The async_batches API supports many functions, each identified as a batch_type. Typically, the task body for a batch_type will be representative of a single request to our standard endpoints, however, some variations may be present.

Related guides: Examples of Async Batches

Scopewrite_batches

Batches will only leverage resources from the same version they are created in. e.g. a batch created with 2021-11 will only process tasks from the 2021-11 version.

Body parameters

batch_typestring
Desired batch type
Possible values
address_discount_applyaddress_discount_removechange_next_charge_datediscount_creatediscount_deletediscount_updateproduct_createproduct_updateproduct_deleteonetime_createonetime_deletebulk_subscriptions_createbulk_subscriptions_updatebulk_subscriptions_deletesubscription_cancel

POST/async_batches

curl -X POST 'https://api.rechargeapps.com/async_batches' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "batch_type": "desired_batch_type"
}'

Response

{
  "async_batch": {
    "id": 19,
    "batch_type": "desired_batch_type",
    "closed_at": null,
    "created_at": "2020-06-05T08:52:10",
    "deleted_at": null,
    "fail_task_count": 0,
    "status": "not_started",
    "submitted_at": null,
    "success_task_count": 0,
    "total_task_count": 0,
    "updated_at": "2020-06-05T08:52:10",
    "expired_at": "2020-07-15T00:00:00",
    "version": "2021-01"
  }
}

#Retrieve a batch

GET/async_batches/{id}

Retrieve a batch using the Recharge batch id. A batch can be retrieved during processing to evaluate batch progress.

## HTTP request examples

GET /async_batches/<batch_id>

GET/async_batches/{id}

curl 'https://api.rechargeapps.com/async_batches/16' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'

Response

{
  "async_batch": {
    "id": 19,
    "batch_type": "desired_batch_type",
    "closed_at": null,
    "created_at": "2020-06-05T08:52:10",
    "deleted_at": null,
    "fail_task_count": 0,
    "status": "not_started",
    "submitted_at": null,
    "success_task_count": 0,
    "total_task_count": 0,
    "updated_at": "2020-06-05T08:52:10",
    "expired_at": "2020-07-15T00:00:00",
    "version": "2021-01"
  }
}

#List batches

GET/async_batches

Returns a list of all your async_batches.

GET/async_batches

curl 'https://api.rechargeapps.com/async_batches' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'

Response

{
  "async_batches": [
    {
      "id": 20,
      "batch_type": "discount_delete",
      "closed_at": null,
      "created_at": "2020-06-05T09:21:37",
      "deleted_at": null,
      "fail_task_count": 0,
      "status": "not_started",
      "submitted_at": null,
      "success_task_count": 0,
      "total_task_count": 40,
      "updated_at": "2020-06-05T09:21:37",
      "version": "2021-01"
    },
    {
      "id": 19,
      "batch_type": "discount_create",
      "closed_at": null,
      "created_at": "2020-06-05T08:52:11",
      "deleted_at": null,
      "fail_task_count": 0,
      "status": "not_started",
      "submitted_at": null,
      "success_task_count": 0,
      "total_task_count": 0,
      "updated_at": "2020-06-05T08:52:11",
      "version": "2021-01"
    },
    {
      "id": 16,
      "batch_type": "discount_create",
      "closed_at": "2020-05-29T09:23:07",
      "created_at": "2020-05-29T09:14:45",
      "deleted_at": null,
      "fail_task_count": 0,
      "status": "completed",
      "submitted_at": "2020-05-29T09:21:33",
      "success_task_count": 2000,
      "total_task_count": 2000,
      "updated_at": "2020-05-29T09:23:07",
      "version": "2021-01"
    }
  ]
}

#Process a batch

POST/async_batches/{batch_id}/process

Until a batch is submitted for processing, no tasks are attempted. Once you have ensured the tasks in a batch are ready for processing, you can submit for processing using this endpoint and the associated batch id.

Webhooks - Batches process quickly, and may result in Recharge dispatching many webhooks at a high rate. Ensure any systems subscribed to resulting webhooks are capable of handling such load.

POST/async_batches/{batch_id}/process

curl -X POST 'https://api.rechargeapps.com/async_batches/21/process' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{}'

Response

{
  "async_batch": {
    "id": 21,
    "batch_type": "discount_create",
    "closed_at": null,
    "created_at": "2020-06-05T10:53:36",
    "deleted_at": null,
    "fail_task_count": 0,
    "status": "processing",
    "submitted_at": "2020-06-05T10:54:54",
    "success_task_count": 0,
    "total_task_count": 10,
    "updated_at": "2020-06-05T10:54:54"
  }
}