Skip to content
Docs
Open Backstage
Reference

BackstageClient.shipments

BackstageClient.shipments in @ticketlayer/backstage.

@ticketlayer/backstage

@ticketlayer/backstage / BackstageClient / shipments

shipments: {
  addItems: (shipmentId: string, request: {
     unitItemIds?: string[];
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }>;
  cancel: (shipmentId: string, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }>;
  create: (unitId: string, request: {
     carrier?: string | null;
     service?: string | null;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }>;
  delivered: (shipmentId: string, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }>;
  dispatch: (shipmentId: string, request: {
     carrier: string;
     service?: string | null;
     trackingNumber: string;
     trackingUrl?: string | null;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }>;
  encode: (shipmentId: string, request: {
     activation?: "immediate" | "on_receipt";
     chipType?: string | null;
     commandId?: string;
     deviceId?: string | null;
     slotId: string;
     uid?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     encoding: {
        activatedAt: string | null;
        activation: "immediate" | "on_receipt";
        chipType: string | null;
        commandId: string | null;
        deviceId: string | null;
        encodedAt: string;
        encodedBy: string | null;
        id: string;
        mediaType: string | null;
        orderId: string;
        passId: string;
        shipmentId: string | null;
        slotId: string;
        uid: string;
     };
     passLink: string | null;
     shipment: {
        accountId: string;
        cancelledAt: string | null;
        carrier: string | null;
        createdAt: string;
        createdBy: string | null;
        deliveredAt: string | null;
        dispatchedAt: string | null;
        dispatchedBy: string | null;
        id: string;
        items: {
           id: string;
           packedAt: string;
           packedBy: string | null;
           passId: string | null;
           scannedCode: string | null;
           unitItemId: string;
        }[];
        orderId: string;
        remaining: {
           entitlementId: string | null;
           passId: string | null;
           storedValueAccountId: string | null;
           unitItemId: string;
        }[];
        returnedAt: string | null;
        returnReason: string | null;
        service: string | null;
        shipTo: {
           city: string;
           country: string;
           line1: string;
           line2?: string | null;
           name: string;
           phone?: string | null;
           postalCode: string;
           region?: string | null;
        };
        status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
        trackingNumber: string | null;
        trackingUrl: string | null;
        unitId: string;
        updatedAt: string;
     };
  }>;
  get: (shipmentId: string, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }>;
  getSettings: (requestOptions?: RequestOptions) => Promise<{
     scanToParcel: boolean;
     updatedAt: string | null;
     updatedBy: string | null;
  }>;
  list: (options?: {
     limit?: number;
     orderId?: string;
     status?: string;
     unitId?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }[]>;
  returned: (shipmentId: string, request: {
     reason: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }>;
  scan: (shipmentId: string, request: {
     code: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  }>;
  setSettings: (request: {
     scanToParcel: boolean;
   }, requestOptions?: RequestOptions) => Promise<{
     scanToParcel: boolean;
     updatedAt: string | null;
     updatedBy: string | null;
  }>;
};

Defined in: client.ts:6863

Shipments methods

addItems()#

addItems: (shipmentId: string, request: {
  unitItemIds?: string[];
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}>;

Put items in a parcel without scanning For an organisation that has turned scan-to-parcel off: puts the named unit items, or every item of the parcel's unit not yet in a parcel, into it without scanning. While scan-to-parcel is on (the default): 409 SCAN_TO_PARCEL_REQUIRED. Needs orders.update on the parcel's account.

Parameters#

ParameterTypeDescription
shipmentIdstring-
request{ unitItemIds?: string[]; }-
request.unitItemIds?string[]Description The unit items to put in. Left out, every item of the parcel's unit not yet in a parcel
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }>

Operation Id#

addShipmentItems

cancel()#

cancel: (shipmentId: string, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}>;

Cancel a parcel being packed Its tickets come out and can go in another. A dispatched parcel cannot be recalled (409 SHIPMENT_NOT_PACKING); mark it returned. Needs orders.update on the parcel's account.

Parameters#

ParameterType
shipmentIdstring
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }>

Operation Id#

cancelShipment

create()#

create: (unitId: string, request: {
  carrier?: string | null;
  service?: string | null;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}>;

Open a parcel for a post unit A parcel to the order's ship-to address (409 SHIP_TO_REQUIRED without one) for a post unit that is not on hold. The unit is now being worked. Needs orders.update on its account.

Parameters#

ParameterTypeDescription
unitIdstring-
request{ carrier?: string | null; service?: string | null; }-
request.carrier?string | nullExample royal_mail
request.service?string | nullDescription Posted tickets default to a signed-for or special delivery service: Royal Mail Tracked 24 does not compensate valuables. Example special_delivery
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }>

Operation Id#

createShipment

delivered()#

delivered: (shipmentId: string, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}>;

Mark a parcel delivered The carrier delivered it. The unit is delivered once all its parcels are. Needs orders.update on the parcel's account.

Parameters#

ParameterType
shipmentIdstring
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }>

Operation Id#

markShipmentDelivered

dispatch()#

dispatch: (shipmentId: string, request: {
  carrier: string;
  service?: string | null;
  trackingNumber: string;
  trackingUrl?: string | null;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}>;

Dispatch a parcel Dispatch with the carrier, service and tracking number, typed or scanned from the label (never fetched from a carrier). Its items are fulfilled; the unit is fulfilled (dispatched) once every item has gone. The buyer is emailed the tracking. An empty parcel: 409 SHIPMENT_EMPTY. With scan-to-parcel on (the organisation's setting, on by default), every item in the parcel must have been scanned in: 409 SHIPMENT_ITEMS_NOT_SCANNED otherwise. Needs orders.update on the parcel's account.

Parameters#

ParameterTypeDescription
shipmentIdstring-
request{ carrier: string; service?: string | null; trackingNumber: string; trackingUrl?: string | null; }-
request.carrierstringExample royal_mail
request.service?string | nullExample special_delivery
request.trackingNumber?stringDescription Typed or scanned from the label Example AB123456789GB
request.trackingUrl?string | nullFormat: uri Description The carrier's tracking page, for the buyer's email
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }>

Operation Id#

dispatchShipment

encode()#

encode: (shipmentId: string, request: {
  activation?: "immediate" | "on_receipt";
  chipType?: string | null;
  commandId?: string;
  deviceId?: string | null;
  slotId: string;
  uid?: string;
}, requestOptions?: RequestOptions) => Promise<{
  encoding: {
     activatedAt: string | null;
     activation: "immediate" | "on_receipt";
     chipType: string | null;
     commandId: string | null;
     deviceId: string | null;
     encodedAt: string;
     encodedBy: string | null;
     id: string;
     mediaType: string | null;
     orderId: string;
     passId: string;
     shipmentId: string | null;
     slotId: string;
     uid: string;
  };
  passLink: string | null;
  shipment: {
     accountId: string;
     cancelledAt: string | null;
     carrier: string | null;
     createdAt: string;
     createdBy: string | null;
     deliveredAt: string | null;
     dispatchedAt: string | null;
     dispatchedBy: string | null;
     id: string;
     items: {
        id: string;
        packedAt: string;
        packedBy: string | null;
        passId: string | null;
        scannedCode: string | null;
        unitItemId: string;
     }[];
     orderId: string;
     remaining: {
        entitlementId: string | null;
        passId: string | null;
        storedValueAccountId: string | null;
        unitItemId: string;
     }[];
     returnedAt: string | null;
     returnReason: string | null;
     service: string | null;
     shipTo: {
        city: string;
        country: string;
        line1: string;
        line2?: string | null;
        name: string;
        phone?: string | null;
        postalCode: string;
        region?: string | null;
     };
     status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
     trackingNumber: string | null;
     trackingUrl: string | null;
     unitId: string;
     updatedAt: string;
  };
}>;

Encode a wristband for a holder and pack it The encode-and-post station: tap a blank wristband for one holder of the parcel's order. Its chip UID (typed, or from the station reader's nfc.read with commandId) is bound to the holder's pass, the holder's entitlements move onto it, and their items are packed into the parcel. With activation on_receipt the band scans only once the holder activates it on arrival. 409 WRISTBAND_ALREADY_ENCODED, PASS_IDENTIFIER_TAKEN, SHIPMENT_SCAN_MISMATCH (not this parcel's holder), SHIPMENT_ITEM_PACKED, SHIPMENT_NOT_PACKING, NFC_READ_UNUSABLE.

Parameters#

ParameterTypeDescription
shipmentIdstring-
request{ activation?: "immediate" | "on_receipt"; chipType?: string | null; commandId?: string; deviceId?: string | null; slotId: string; uid?: string; }-
request.activation?"immediate" | "on_receipt"Description immediate (the default): the band scans at once. on_receipt: it scans once the holder activates it on arrival
request.chipType?string | nullDescription With a typed uid; taken from the command with commandId Example NTAG213
request.commandId?stringDescription The station reader's completed nfc.read or nfc.encode (a relay command): the UID is taken from its checked result. 409 NFC_READ_UNUSABLE when it is not complete, older than 15 minutes or not an NFC command
request.deviceId?string | nullDescription The reader that read a typed uid; taken from the command with commandId
request.slotId?stringDescription The holder the band is for (GET /orders/{orderId}/holders)
request.uid?stringDescription The chip's UID, hex (4, 7 or 10 bytes; colons and spaces are ignored), from a reader in keyboard mode. Or give commandId Example 04A224B2C35E80
requestOptions?RequestOptions-

Returns#

Promise<{ encoding: { activatedAt: string | null; activation: "immediate" | "on_receipt"; chipType: string | null; commandId: string | null; deviceId: string | null; encodedAt: string; encodedBy: string | null; id: string; mediaType: string | null; orderId: string; passId: string; shipmentId: string | null; slotId: string; uid: string; }; passLink: string | null; shipment: { accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }; }>

Operation Id#

encodeIntoShipment

get()#

get: (shipmentId: string, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}>;

Get a parcel One parcel with what is in it and what of its unit remains. Needs orders.read on its account.

Parameters#

ParameterType
shipmentIdstring
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }>

Operation Id#

getShipment

getSettings()#

getSettings: (requestOptions?: RequestOptions) => Promise<{
  scanToParcel: boolean;
  updatedAt: string | null;
  updatedBy: string | null;
}>;

Get the organisation's fulfilment settings Scan-to-parcel: on by default, so items go into a tracked parcel by scanning and it is dispatched only when every item in it was scanned in. Needs orders.read on some account.

Parameters#

ParameterType
requestOptions?RequestOptions

Returns#

Promise<{ scanToParcel: boolean; updatedAt: string | null; updatedBy: string | null; }>

Operation Id#

getFulfilmentSettings

list()#

list: (options?: {
  limit?: number;
  orderId?: string;
  status?: string;
  unitId?: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}[]>;

List parcels Parcels, by order, unit or status, oldest first, for the accounts the caller can read. Each with what is in it and what of its unit is not yet in any parcel. Needs orders.read.

Parameters#

ParameterType
options?{ limit?: number; orderId?: string; status?: string; unitId?: string; }
options.limit?number
options.orderId?string
options.status?string
options.unitId?string
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }[]>

Operation Id#

listShipments

returned()#

returned: (shipmentId: string, request: {
  reason: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}>;

Mark a parcel returned It came back: its items are marked returned and a task is raised for staff to decide what next. Needs orders.update on the parcel's account.

Parameters#

ParameterType
shipmentIdstring
request{ reason: string; }
request.reasonstring
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }>

Operation Id#

markShipmentReturned

scan()#

scan: (shipmentId: string, request: {
  code: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  cancelledAt: string | null;
  carrier: string | null;
  createdAt: string;
  createdBy: string | null;
  deliveredAt: string | null;
  dispatchedAt: string | null;
  dispatchedBy: string | null;
  id: string;
  items: {
     id: string;
     packedAt: string;
     packedBy: string | null;
     passId: string | null;
     scannedCode: string | null;
     unitItemId: string;
  }[];
  orderId: string;
  remaining: {
     entitlementId: string | null;
     passId: string | null;
     storedValueAccountId: string | null;
     unitItemId: string;
  }[];
  returnedAt: string | null;
  returnReason: string | null;
  service: string | null;
  shipTo: {
     city: string;
     country: string;
     line1: string;
     line2?: string | null;
     name: string;
     phone?: string | null;
     postalCode: string;
     region?: string | null;
  };
  status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing";
  trackingNumber: string | null;
  trackingUrl: string | null;
  unitId: string;
  updatedAt: string;
}>;

Scan a ticket into a parcel Scan to pack: a printed ticket's barcode (or any active identifier of its pass) puts every item of the unit on that pass into the parcel. Unknown code: 404 SHIPMENT_SCAN_UNKNOWN. Another order's ticket: 409 SHIPMENT_SCAN_MISMATCH, and a task is raised. Already packed: 409 SHIPMENT_ITEM_PACKED; cancelled: 409 FULFILMENT_ITEM_CANCELLED. Needs orders.update on the parcel's account.

Parameters#

ParameterTypeDescription
shipmentIdstring-
request{ code: string; }-
request.codestringDescription A printed ticket's barcode, or any active identifier of its pass; for a gift card, its id (sva_...) printed as its label - never its code
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string; cancelledAt: string | null; carrier: string | null; createdAt: string; createdBy: string | null; deliveredAt: string | null; dispatchedAt: string | null; dispatchedBy: string | null; id: string; items: { id: string; packedAt: string; packedBy: string | null; passId: string | null; scannedCode: string | null; unitItemId: string; }[]; orderId: string; remaining: { entitlementId: string | null; passId: string | null; storedValueAccountId: string | null; unitItemId: string; }[]; returnedAt: string | null; returnReason: string | null; service: string | null; shipTo: { city: string; country: string; line1: string; line2?: string | null; name: string; phone?: string | null; postalCode: string; region?: string | null; }; status: "cancelled" | "delivered" | "dispatched" | "returned" | "packing"; trackingNumber: string | null; trackingUrl: string | null; unitId: string; updatedAt: string; }>

Operation Id#

scanIntoShipment

setSettings()#

setSettings: (request: {
  scanToParcel: boolean;
}, requestOptions?: RequestOptions) => Promise<{
  scanToParcel: boolean;
  updatedAt: string | null;
  updatedBy: string | null;
}>;

Set the organisation's fulfilment settings Turns scan-to-parcel on or off for the organisation. Off, staff can also put items in a parcel without scanning (POST /fulfilment/shipments/{shipmentId}/items). Needs settings.update on every account.

Parameters#

ParameterType
request{ scanToParcel: boolean; }
request.scanToParcelboolean
requestOptions?RequestOptions

Returns#

Promise<{ scanToParcel: boolean; updatedAt: string | null; updatedBy: string | null; }>

Operation Id#

putFulfilmentSettings