Submit a Batch Processing Request
Bold provides a Batch Process endpoint that enables you to send more than one request to Bold Checkout at a time. By submitting a series of requests at once, you can cut down the amount of time spent on network requests.
This document outlines the structure and use of the Batch Process endpoint.
How it works
The Batch Process endpoint accepts a series of sub-requests in an array called sub_requests. Each sub-request is composed of the endpoint URL, the HTTP method, and the request data.
For the purpose of rate limiting, a Batch Process call is counted as one request.
Bold processes the sub-requests in the order they are indexed in the request. If one of the sub-requests returns an error, processing halts and any requests after the failed request are not processed.
Include the request data in the payload, exactly as it would be formatted in a standard API request. For requests that normally use a query parameter, include that data as part of the request body. See the example below.
If an endpoint does not have parameters or a body, simply leave the payload object empty ({}).
The following cURL snippet shows an example of submitting a Batch Process request to validate an email address and add a guest customer to the order. In this scenario, if the email address validation failed, then the guest customer would not be added to the order.
curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/batch' \
--header 'Authorization: Bearer {access_token}' \
--header 'Bold-API-Version-Date: 2022-05-01' \
--header 'Content-Type: application/json' \
--data '{
"sub_requests": [
{
"method": "GET",
"endpoint": "/validate_email_address",
"payload": {
"email_address": "[email protected]"
}
},
{
"method": "POST",
"endpoint": "/customer/guest",
"payload": {
"first_name": "John",
"last_name": "Doe",
"email_address": "[email protected]",
"accepts_marketing": true
}
}
]
}'
Supported endpoints
Batch processing is not available for all endpoints. The following table shows which endpoints in the Checkout Frontend API are eligible for batch processing:
| Resource | Endpoint URL | Batch processing supported? |
|---|---|---|
| Addresses | /addresses/billing | Yes |
| Addresses | /addresses/shipping | Yes |
| Customers | /customer | Yes |
| Customers | /customer/guest | Yes |
| Customers | /validate_email_address | Yes |
| Discounts | /discounts | Yes |
| Discounts | /validate_discount_code | No |
| Line Items | /items | Yes |
| Metadata | /meta_data | Yes |
| Orders | /process_order | Yes |
| Orders | /pre_process_order | No |
| Orders | /amend_order | No |
| Orders | /refresh | No |
| Orders | /app_hook | Yes |
| Orders | /check_inventory | Yes |
| Payments | /payments | Yes |
| Payments | /payments/gift_card | Yes |
| Payment Iframes | /payments/styles | No |
| Shipping Lines | /shipping_lines | Yes |
| Taxes | /taxes | Yes |
Remote State Authority (RSA) support
Checkout RSA enables your platform to serve as the authority on the order state throughout the checkout process. If you are using the Batch Process endpoint with Checkout RSA, you cannot mix requests that trigger RSA events with those that do not.
For example, let's say your store uses RSA and you want to make the following API calls using the Batch Process endpoint:
- Add Guest Customer
- Add Shipping Address
- Select Shipping Line
- Add Payment
- Process Order
Based on the events supported by the RSA Process Order Events endpoint, Add Payment and Process Order are not supported on RSA. Therefore, you need to make two Batch Process requests.
The first request handles RSA-compatible endpoints:
- Add Guest Customer
- Add Shipping Address
- Select Shipping Line
curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/batch' \
--header 'Authorization: Bearer {access_token}' \
--header 'Bold-API-Version-Date: 2022-05-01' \
--header 'Content-Type: application/json' \
--data '{
"sub_requests": [
{
"method": "POST",
"endpoint": "/customer/guest",
"payload": {
"first_name": "John",
"last_name": "Doe",
"email_address": "[email protected]",
"accepts_marketing": true
}
},
{
"method": "POST",
"endpoint": "/addresses/shipping",
"payload": {
"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
{
"method": "POST",
"endpoint": "/shipping_lines",
"payload": {
"index": "0"
}
}
]
}'
The second request handles non-RSA-compatible endpoints:
- Add Payment
- Process Order
curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/batch' \
--header 'Authorization: Bearer {access_token}' \
--header 'Bold-API-Version-Date: 2022-05-01' \
--header 'Content-Type: application/json' \
--data '{
"sub_requests": [
{
"method": "POST",
"endpoint": "/payments",
"payload": {
"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false,
"payment_parameters": {
"is_giftcard": true,
"customer_segment_id": "ab4329tn23oe315"
}
}
},
{
"method": "POST",
"endpoint": "/process_order",
"payload": {}
}
]
}'