Skip to content

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:

ts
// 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).

ts
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:

ts
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:

ts
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 ​

ts
await zr.parcels.createExchangeBulk({ /* … */ }); // ≤ 100
await zr.parcels.createRefundBulk({ /* … */ });   // ≤ 100, balance-checked

All bulk variants share the no-throw envelope contract.

Released under the MIT License. Not affiliated with ZR Express.