Bulk Operations
Bulk parcel operations are designed for partial success. They return the same envelope on 200 (all succeeded), 207 (partial), and 400 (all failed) — and the SDK never throws on 207/400. You inspect the result; you opt into throwing.
The envelope
Each bulk operation returns its own response type (e.g. CreateBulkParcelsResponse) with the same shape:
// e.g. CreateBulkParcelsResponse
{
totalRequested?: number | null;
successCount?: number | null;
failureCount?: number | null;
successes?: { index; parcelId; trackingNumber; externalId }[] | null;
failures?: { index; errorCode; errorMessage; externalId }[] | null;
}The exported BulkResultEnvelope interface is the common subset (totalRequested, successCount, failureCount, failures) that assertBulkOk reads.
Create in bulk
createBulk accepts up to 100 parcels. Each entry is a SingleParcelCreationRequest with the same verified required fields as a single create (valid productId + productSku, a valid customer.phone.number1, a deliverable deliveryType).
const result = await zr.parcels.createBulk({
parcels: [
/* SingleParcelCreationRequest, … up to 100 */
],
});
console.log(`${result.successCount}/${result.totalRequested} created`);
for (const failure of result.failures ?? []) {
console.warn(failure.externalId, failure.errorCode, failure.errorMessage);
}Bulk creates are never retried.
Opt-in throwing: assertBulkOk
When you want a failed batch to throw, pass the result through assertBulkOk. It returns the envelope unchanged if nothing failed, otherwise throws ZrExpressBulkError carrying failures:
import { assertBulkOk, ZrExpressBulkError } from '@terminaldz/zrexpress-sdk';
try {
const ok = assertBulkOk(await zr.parcels.createBulk({ parcels }));
// every item succeeded
} catch (err) {
if (err instanceof ZrExpressBulkError) {
console.error(`${err.failures.length} failed`, err.failures);
}
}Delete in bulk
deleteBulk and deleteBulkByTrackingNumber accept up to 200 ids/tracking numbers and return the same envelope semantics:
const del = await zr.parcels.deleteBulk({ parcelIds: ['…', '…'] });
console.log(del.successCount, del.failureCount);Deletion notes: deleting a parcel with a ReturnParcel cascades; ExchangeReturn parcels cannot be deleted; deleting a ReturnParcel resets the original's IsExchanged.
Exchange & refund in bulk
await zr.parcels.createExchangeBulk({ /* … */ }); // ≤ 100
await zr.parcels.createRefundBulk({ /* … */ }); // ≤ 100, balance-checkedAll bulk variants share the no-throw envelope contract.