For agent builders & AI-assisted businesses
Your agent connects the dots. Ysend connects the orders, stock, warehouse work and shipment progress—so a digital decision has a real operational next step.
The TypeScript SDK exposes inventory, orders and shipments as typed domains. Start with a small server-side read workflow, then qualify the operations your integration needs.
import { Ysend } from "@ysend/sdk";
const ysend = new Ysend({
baseUrl: process.env.YSEND_API_BASE_URL!,
apiKey: process.env.YSEND_API_KEY!,
});
const stock = await ysend.inventory.listBalances({ page: 1, pageSize: 20 });
const orders = await ysend.orders.list({ status: "Open", page: 1, pageSize: 20 });
const shipments = await ysend.shipments.list({ page: 1, pageSize: 20 });Inspect the reason, correct the row or resolve its mapping, and resubmit it.
import type {
Ysend, ImportPortalOrdersInput,
CorrectPortalOrderImportRowInput, ResubmitOrderImportInput,
} from "@ysend/sdk";
export async function importBatch(
ysend: Ysend, input: ImportPortalOrdersInput, operationKey: string,
) {
const result = await ysend.orders.importManual(input, operationKey);
// Quarantined rows are not imported orders. null means a count was not returned.
return { imported: result.imported ?? null, quarantined: result.quarantined ?? null };
}
export async function listExceptionPage(ysend: Ysend, page: number) {
// Tenant-wide queue, not this batch's results. Review further pages as needed.
// Match batchReference and orderCode before choosing an exception to correct.
return ysend.orders.listQuarantine({ page, pageSize: 20 });
}
export async function correctOrder(
ysend: Ysend, exceptionId: number,
correction: CorrectPortalOrderImportRowInput, operationKey: string,
) {
// Saves the correction only. A separate, authorised action must resubmit it.
await ysend.orders.correctQuarantinedRow(
exceptionId, correction, operationKey,
);
}
export async function resubmitOrder(
ysend: Ysend, exceptionId: number,
resubmission: ResubmitOrderImportInput, operationKey: string,
) {
// Use this resubmission's own stable key; inspect the returned counts again.
const result = await ysend.orders.resubmitQuarantinedRow(
exceptionId, resubmission, operationKey,
);
return { imported: result.imported ?? null, quarantined: result.quarantined ?? null };
}Your agent can read stock, send orders, review orders that need correcting, then follow shipments and open returns through the Ysend API. When it retries a change, it reuses the same request key so nothing is created twice.
Authorised teams follow orders and returns in the merchant mobile workspace; warehouse staff use supported handheld scanning workflows.
ApplicationsFollow the operation
Who takes this stepYour application / agent
Read the warehouse-scoped balance before supplying demand. Your application applies its selling rules to available stock after existing commitments before proposing new orders.
Your application can propose this demand. Warehouse stock remains controlled by physical operations.
Who takes this stepYour integration → Ysend orders
Send recognised product references, recipient details and quantities using a stable batch reference. The response separates accepted rows from rows held for correction; a successful request alone is insufficient.
Let accepted orders proceed. Inspect exceptions before treating the batch as complete.
Who takes this stepYour integration and catalogue reviewer
Review the account's paginated quarantine queue and identify the affected rows. Resolve each product reference, correct the row and resubmit it with a distinct stable retry key for that operation.
A correction and a resubmission are separate actions. Confirm each result before closing the exception.
Who takes this stepWarehouse operator
The warehouse works the accepted demand through picking and packing. Operators identify the product and complete the required checks; your agent follows order progress rather than marking physical work complete itself.
Warehouse staff resolve a missing scan or packing exception before handing the affected parcel to transport.
Who takes this stepYour application and customer service
Your application retains the shipment identifier supplied by its integration or operational handoff, then reads that shipment. The SDK's shipment read needs that known identifier; it does not discover an order-to-shipment link.
Your application applies its communication rules using the available shipment events.
Who takes this stepCustomer service → returns team
When a customer reports damage after delivery, open a return against that order and add evidence. The returns team records physical handling; your business decides the commercial response from that record.
An opened return is the start of aftercare. Inspection, stock disposition and any refund remain distinct decisions.
A server-side key has the intended scopes, and your product references resolve to the correct warehouse items.
You can read accepted rows, find a quarantined row, correct it and confirm its explicit resubmission.
Your team can connect an order to its shipment and return, with an owner for every unresolved decision.
We qualify your application's connection against the supported APIs and required account permissions. The SDK is an integration building block; external-agent access is prepared with the Ysend team.
Agents can work with exposed operational data and supported actions. Physical handling, commercial decisions and operations requiring approval retain their own responsible teams and controls.
The SDK is supplied as a versioned package through the authorised developer portal. We confirm your environment, credentials and integration scope during onboarding.
Plan your next step
Tell us what your agent should read, which actions it should coordinate, and where orders and stock live today. We will map the connection with your team.