> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt > Use this file to discover all available pages before exploring further. # Create VAS by return inventory ID > Create value-added service requests for one or more return inventories. Inventory must be set to On-hold handling before creating VAS. Split parcel VAS must be submitted separately from other VAS types. Requests one or more value-added services (VAS) on received return inventory — quality inspection, repackaging, photo, split-parcel, etc. The warehouse executes the VAS and reports results back via subsequent webhook events. ## Prerequisites * Target inventory items exist and belong to your account. The `returnInventoryId` values come from the `newInventoryCreated` webhook event — cache them on your side as parcels are logged. * Each target inventory's `handlingCode` must be `ohd` (on-hold). VAS is only allowed while the inventory is on-hold; if it's already in another handling pathway, move it back to on-hold first via [Update return inventory handling](/api-reference/returninventory/update-return-inventory-handling). * Pick valid `vasCode` values from [Get all VAS](/api-reference/vas/get-all-value-added-services). ## Required fields * **`createVasList`** — non-empty list of payloads. Each payload covers one inventory and one or more VAS requests on it. Per payload: * **`returnInventoryId`** — string that parses to a long; must exist and be on-hold. * **`createVasDetailList`** — list of VAS detail objects, each carrying a `vasCode` and any VAS-specific fields. `returnInventoryId` values across the whole batch must be unique — you cannot create two payloads for the same inventory in one call. ## Split-parcel rule If any VAS in a payload uses `vasCode: SPLIT_PARCEL`: * It must be the **only** VAS in that payload's `createVasDetailList` (you can't combine split-parcel with other VAS in a single payload for the same inventory). * File attachments are allowed (and typically required) only for `SPLIT_PARCEL`. Other VAS codes cannot have file attachments. This is enforced because split-parcel changes the physical inventory shape; bundling it with other VAS would create ambiguity about ordering. ## Side effects * The inventory's handling stays at `ohd` while VAS is pending. * Subsequent webhook events report progress: `vasUpdated`, , `splitLineItem` and `newInventoryCreated` (For parcel split). * For split-parcel VAS, completion may produce additional inventory records (the split items). ## Related * [Get all VAS](/api-reference/vas/get-all-value-added-services) — valid `vasCode` values. * [Get all VAS statuses](/api-reference/vasstatus/get-all-vas-statuses) — code-to-label mappings for VAS lifecycle. * [Update return inventory handling](/api-reference/returninventory/update-return-inventory-handling) — move an inventory back to `ohd` if it's left that state. * [Webhooks](/webhooks) — the `vasUpdated` event reports VAS lifecycle progress to your endpoint. ## OpenAPI ````yaml post /api/Vas/CreateByReturnInventoryId openapi: 3.1.0 info: title: Return Helper API description: API documentation for Return Helper — covering User and Public endpoints. version: 1.0.0 servers: - url: https://api.returnshelper.com/uat/user description: Sandbox — User API - url: https://api.returnshelper.com/uat/public description: Sandbox — Public API - url: https://api.returnhelpercentre.com/v1/user description: Production — User API - url: https://api.returnhelpercentre.com/v1/public description: Production — Public API - url: https://api.returnhelperchina.com/user description: Production — User API (China) security: - ApiKey: [] ApiToken: [] paths: /api/Vas/CreateByReturnInventoryId: post: tags: - Vas summary: Create VAS by return inventory ID description: >- Create value-added service requests for one or more return inventories. Inventory must be set to On-hold handling before creating VAS. Split parcel VAS must be submitted separately from other VAS types. operationId: ReturnUserApi_CreateVasByReturnInventoryId requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVasByReturnInventoryIdRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GeneralList_CreateVasReply' '401': description: >- Authentication failed. Returned when the `x-rr-apikey` or `x-rr-apitoken` header is missing or invalid. The body uses the standard `ApiResponse` envelope with `meta.error.message` describing the auth failure. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' security: - ApiKey: [] ApiToken: [] servers: - url: https://api.returnshelper.com/uat/user description: Sandbox — User API components: schemas: CreateVasByReturnInventoryIdRequest: type: object properties: createVasList: type: array items: $ref: '#/components/schemas/CreateVasByReturnInventoryIdPayload' description: List of VAS creation payloads grouped by return inventory ID required: - createVasList GeneralList_CreateVasReply: type: object properties: data: type: array items: $ref: '#/components/schemas/CreateVasReply' description: List of created VAS ApiResponse: type: object description: >- Universal response envelope. Successful responses include the business payload as additional top-level fields alongside `correlationId` and `meta`. Failed responses (auth errors, validation errors) only populate `correlationId` and `meta`, with `meta.errorCode` and `meta.error` describing the failure. properties: correlationId: type: - string - 'null' description: >- Unique correlation ID for tracing the request through Return Helper systems. meta: $ref: '#/components/schemas/ApiResponseMeta' CreateVasByReturnInventoryIdPayload: type: object properties: returnInventoryId: type: string description: Return inventory ID to create VAS for createVasDetailList: type: array items: $ref: '#/components/schemas/CreateVasDetail' description: List of VAS details to create required: - returnInventoryId - createVasDetailList CreateVasReply: type: object properties: returnRequestLineItemId: type: integer format: int64 createVasDetailList: type: array items: type: object description: '(see source: CreateVasDetailReply)' ApiResponseMeta: type: object description: >- Application-level metadata for every API response. Inspect `status` and `errorCode` to detect soft-error responses (validation failures arrive as HTTP 200 with `meta.status: 400`). properties: status: type: integer description: >- Application-level status code. For successful operations this mirrors the HTTP status (e.g. 200). For validation failures it reports the logical status (e.g. 400) even though the wire HTTP status is 200. data: type: object additionalProperties: type: string description: Reserved free-form metadata key/value pairs. Usually empty. errorCode: type: - string - 'null' description: >- Machine-readable error code (e.g. `VALIDATION_FAILED`). Non-null only when the operation failed. error: type: object additionalProperties: true description: >- Field-level or message-level error detail keyed by request property name. Empty object on success. CreateVasDetail: type: object properties: vasCode: type: string description: >- VAS code to create (e.g. use Get All VAS to retrieve available codes) notes: type: - string - 'null' description: Additional notes for the VAS request metaQuantity: type: integer format: int32 description: Quantity for the VAS operation (applicable for split parcel) vasFileList: type: - array - 'null' items: $ref: '#/components/schemas/CreateVasFilePayload' description: Files for the VAS request (applicable for split parcel only) required: - vasCode CreateVasFilePayload: type: object properties: filename: type: string description: Filename of the VAS file fileKey: type: string description: S3 file key of the uploaded file required: - filename - fileKey securitySchemes: ApiKey: type: apiKey in: header name: x-rr-apikey description: Your API key ApiToken: type: apiKey in: header name: x-rr-apitoken description: Your API token — keep this private ````