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

13 additions in V2, marked New

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

Endpoints

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

#The async batch object

Async batch contains all the setups information and status update of a batch of operation to be performed collectively.

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.

Attributes

idinteger
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
address_updatebulk_customer_notification_preferences_accepted_updatebulk_customer_notification_preferences_declined_updatebulk_customers_updatebulk_plans_createbulk_plans_deletebulk_plans_updatebundle_bulk_swapbundle_selection_assignbundle_selection_updatebundle_selections_deletebundle_selections_sync_pricecharge_processcredit_account_createcredit_account_updatediscount_creatediscount_deletediscount_updatefree_gifts_addfree_gifts_removeonetime_createonetime_deleteonetime_updateplan_createproduct_variant_tax_code_updatesubscription_update
closed_atdatetime
Indicates the date and time that processing was completed for a batch
expired_atdatetimeNew
The date and time until which the batch and its tasks are retained.
deleted_atdatetime · nullableNew
The date and time the batch was deleted. Deleted batches are not returned by the API, so this is null.
created_atdatetime
Indicates the date and time a batch was created
fail_task_countinteger
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
Possible values
not_startedprocessingrunningcompletedfailedterminated
submitted_atdatetime
Indicates the date and time that a batch was triggered to process
success_task_countinteger
Indicates the number of successful tasks in a batch, during or after processing.
total_task_countinteger
Indicates the total number of tasks in a batch
updated_atdatetime
Indicates the date and time at which a batch was last updated
versionstring
Indicates the API version of the batch. 2021-11 is V2.
Possible values
2021-012021-11
read-only field

The async batch object

{
  "async_batch": {
    "id": 19,
    "batch_type": "discount_create",
    "closed_at": null,
    "created_at": "2022-02-17T08:52:10+00:00",
    "deleted_at": null,
    "expired_at": "2022-03-19T08:52:10+00:00",
    "fail_task_count": 0,
    "status": "not_started",
    "submitted_at": null,
    "success_task_count": 0,
    "total_task_count": 0,
    "updated_at": "2022-02-17T08:52:10+00:00",
    "version": "2021-11"
  }
}

#Batch typesNew

The values accepted for batch_type. Besides write_batches, a token needs the scope of the resource a batch operates on. A batch can hold up to 10,000 tasks.

Batch type	What each task does	Scope required
`address_update` New	Updates one `Address` per task.	`write_customers`
`bulk_customer_notification_preferences_accepted_update` New	Records that a `Customer` accepted a notification preference, one per task.	`write_customers`
`bulk_customer_notification_preferences_declined_update` New	Records that a `Customer` declined a notification preference, one per task.	`write_customers`
`bulk_customers_update` New	Updates one `Customer` per task.	`write_customers`
`bulk_plans_create`	Creates up to 20 `Plans` for one product per task.	`write_plans`
`bulk_plans_update`	Updates up to 20 `Plans` of one product per task.	`write_plans`
`bulk_plans_delete`	Deletes up to 20 `Plans` of one product per task.	`write_plans`
`bundle_bulk_swap` New	Swaps items in the `BundleSelection` of one `Subscription` per task.	`write_subscriptions`
`bundle_selection_assign` New	Creates or replaces the `BundleSelection` of one `Subscription` per task.	`write_subscriptions`
`bundle_selection_update` New	Updates one `BundleSelection` per task.	`write_subscriptions`
`bundle_selections_delete` New	Removes items from the `BundleSelection` of one `Subscription` per task.	`write_subscriptions`
`bundle_selections_sync_price` New	Recalculates the item prices of one `BundleSelection` per task.	`write_subscriptions`
`charge_process` New	Processes one `Charge` per task.	`write_payments`
`credit_account_create` New	Creates one credit account per task.	`write_credit_accounts`
`credit_account_update` New	Updates one credit account per task.	`write_credit_accounts`
`discount_create`	Creates one `Discount` per task. The task body is the body of a create discount request.	`write_discounts`
`discount_delete`	Deletes one `Discount` per task.	`write_discounts`
`discount_update`	Updates one `Discount` per task.	`write_discounts`
`free_gifts_add` New	Adds free gift items to one `Charge` per task.	`write_subscriptions`
`free_gifts_remove` New	Removes free gift items from one `Charge` per task.	`write_subscriptions`
`onetime_create`	Creates one `Onetime` per task. The task body is the body of a create onetime request.	`write_subscriptions`
`onetime_delete`	Deletes one `Onetime` per task.	`write_subscriptions`
`onetime_update` New	Updates one `Onetime` per task.	`write_subscriptions`
`plan_create` New	Creates one `Plan` per task. The task body is the body of a create plan request.	`write_plans`
`product_variant_tax_code_update` New	Sets the tax code of one product variant per task.	`write_products`
`subscription_update` New	Updates one `Subscription` per task.	`write_subscriptions`

#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 V2 will only process tasks from the V2 version.

In addition to write_batches, the token needs the write scope of the resource the batch type operates on (for example write_discounts for discount_create); otherwise 403 is returned. A batch can hold at most 10,000 tasks.

Body parameters

batch_typestringRequired
Desired batch type
Possible values
address_updatebulk_customer_notification_preferences_accepted_updatebulk_customer_notification_preferences_declined_updatebulk_customers_updatebulk_plans_createbulk_plans_deletebulk_plans_updatebundle_bulk_swapbundle_selection_assignbundle_selection_updatebundle_selections_deletebundle_selections_sync_pricecharge_processcredit_account_createcredit_account_updatediscount_creatediscount_deletediscount_updatefree_gifts_addfree_gifts_removeonetime_createonetime_deleteonetime_updateplan_createproduct_variant_tax_code_updatesubscription_update
tasksarray of objectsNew
Optional list of tasks to add to the batch when it is created. A single request can contain at most 1,000 tasks.
Show child attributesHide child attributes11 new
- bodyobjectNew
  The body of the task, in the format required by the batch_type.

POST/async_batches

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

Response

{
  "async_batch": {
    "id": 19,
    "batch_type": "discount_create",
    "closed_at": null,
    "created_at": "2022-10-12T20:16:09+00:00",
    "deleted_at": null,
    "expired_at": "2022-03-19T08:52:10+00:00",
    "fail_task_count": 0,
    "status": "not_started",
    "submitted_at": null,
    "success_task_count": 0,
    "total_task_count": 0,
    "updated_at": "2022-10-12T20:16:09+00:00",
    "version": "2021-11"
  }
}

#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>

Scoperead_batches

GET/async_batches/{id}

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

Response

{
  "async_batch": {
    "id": 19,
    "batch_type": "discount_create",
    "closed_at": null,
    "created_at": "2022-10-12T20:16:09+00:00",
    "deleted_at": null,
    "expired_at": "2022-03-19T08:52:10+00:00",
    "fail_task_count": 0,
    "status": "not_started",
    "submitted_at": null,
    "success_task_count": 0,
    "total_task_count": 0,
    "updated_at": "2022-10-12T20:16:09+00:00",
    "version": "2021-11"
  }
}

#List batches

GET/async_batches

Returns a list of all your async_batches.

Scoperead_batches

The response includes next_cursor and previous_cursor. Batches in the list response do not include updated_at.

Query parameters

batch_typestringNew
Filter batches by batch_type. Any registered batch type can be used as a filter, including types that can only be created with API version 2021-01.
Possible values
address_discount_applyaddress_discount_removeaddress_updatebulk_customer_notification_preferences_accepted_updatebulk_customer_notification_preferences_declined_updatebulk_customers_updatebulk_plans_createbulk_plans_deletebulk_plans_updatebulk_subscriptions_createbulk_subscriptions_deletebulk_subscriptions_updatebundle_bulk_swapbundle_selection_assignbundle_selection_updatebundle_selections_deletebundle_selections_sync_pricechange_next_charge_datecharge_processcredit_account_createcredit_account_updatediscount_creatediscount_deletediscount_updatefree_gifts_addfree_gifts_removeonetime_createonetime_deleteonetime_updateplan_createproduct_createproduct_deleteproduct_updateproduct_variant_tax_code_updatesubscription_cancelsubscription_update
statusstringNew
Filter batches by status.
Possible values
not_startedprocessingrunningcompletedfailedterminated
sort_bystringNew
Sort order of the results. Defaults to id-desc.
Possible values
id-ascid-desccreated_at-asccreated_at-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 batches 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

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

Response

{
  "async_batches": [
    {
      "id": 20,
      "batch_type": "discount_delete",
      "closed_at": null,
      "created_at": "2022-10-12T20:16:09+00:00",
      "deleted_at": null,
      "expired_at": "2022-03-19T08:52:10+00:00",
      "fail_task_count": 0,
      "status": "not_started",
      "submitted_at": null,
      "success_task_count": 0,
      "total_task_count": 40,
      "updated_at": "2022-10-12T20:16:09+00:00",
      "version": "2021-11"
    },
    {
      "id": 19,
      "batch_type": "discount_update",
      "closed_at": null,
      "created_at": "2022-10-12T20:16:09+00:00",
      "deleted_at": null,
      "expired_at": "2022-03-19T08:52:10+00:00",
      "fail_task_count": 0,
      "status": "not_started",
      "submitted_at": null,
      "success_task_count": 0,
      "total_task_count": 0,
      "updated_at": "2022-10-12T20:16:09+00:00",
      "version": "2021-11"
    },
    {
      "id": 16,
      "batch_type": "discount_create",
      "closed_at": "2022-10-12T20:16:09+00:00",
      "created_at": "2022-10-12T20:16:09+00:00",
      "deleted_at": null,
      "expired_at": "2022-03-19T08:52:10+00:00",
      "fail_task_count": 0,
      "status": "completed",
      "submitted_at": "2022-10-12T20:16:09+00:00",
      "success_task_count": 2000,
      "total_task_count": 2000,
      "updated_at": "2022-10-12T20:16:09+00:00",
      "version": "2021-11"
    }
  ]
}

#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.

Scopewrite_batches

Returns 202 with the batch. The batch must have status not_started and contain at least one task, and by default only one batch per store can be processing at a time; otherwise 422 is returned.

POST/async_batches/{batch_id}/process

curl -X POST 'https://api.rechargeapps.com/async_batches/21/process' \
  -H 'X-Recharge-Version: v2' \
  -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": "2022-06-05T10:53:36+00:00",
    "deleted_at": null,
    "expired_at": "2022-03-19T08:52:10+00:00",
    "fail_task_count": 0,
    "status": "processing",
    "submitted_at": "2022-06-05T10:54:54+00:00",
    "success_task_count": 0,
    "total_task_count": 10,
    "updated_at": "2022-06-05T10:54:54+00:00",
    "version": "2021-11"
  }
}

#Delete a batchNew

DELETE/async_batches/{id}

Deletes a batch. Only batches with status not_started, processing or running can be deleted. The token also needs the write scope of the resource the batch type operates on.

Scopewrite_batches

DELETE/async_batches/{id}

curl -X DELETE 'https://api.rechargeapps.com/async_batches/129593' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

No content is returned for this response.

#Terminate a batchNew

PUT/async_batches/{id}

Stops a batch by setting its status to terminated. Only batches with status not_started, processing or running can be terminated. terminated is the only status that can be set through this endpoint.

Scopewrite_batches

Body parameters

statusstringRequired
The new status of the batch. Must be terminated.
Possible values
terminated

PUT/async_batches/{id}

curl -X PUT 'https://api.rechargeapps.com/async_batches/129593' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{}