VAS

Endpoints

Method	Endpoint	Description
GET	/api/v202608/vas	Retrieve VAS list
POST	/api/v202608/vas	Create VAS
DELETE	/api/v202608/vas/{vas_id}	Cancel VAS
GET	/api/v202608/vas-docs	Retrieve VAS attachments
POST	/api/v202608/vas-docs	Upload VAS attachment
DELETE	/api/v202608/vas-docs/{doc_id}	Delete VAS attachment

[NEW] v202608 New Endpoints (2026-09 Patch): All 6 VAS endpoints below are new in this release; v202206 does not provide them.

VAS stands for "Value-Added Service" — extra warehouse operations beyond standard receiving/shipping, such as relabeling, changing SKU, remeasuring, assembly, splitting, disposal, photo, repackaging, cycle count, and labeling.

VAS does not provide an update endpoint. To modify a VAS order, cancel the old one and create a new one.

Key	Value
Authorization	Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...

GET /api/v202608/vas (Retrieve VAS list)

The response always returns the complete detail structure. The vas_id parameter only serves as a filter.

Request

Params

Type	Name	Description	Required/Optional	Schema
query	api	API type Available Values: index.by-default	required	enum
query	vas_id	VAS id	optional	integer
query	vas_type	VAS type id Available Values: 1: General (generic handling; the actual work is described in `description`; the only type that supports `inventory_source = 5 Conditioned`) 2: Relabel / Change SKU (replace the item's outer label and reassign SKU ownership at the same time — the two actions are two facets of the same operation) 3: Remeasure (re-measure item dimensions and weight) 4: Assembly (assemble multiple SKUs into a new kit SKU per bundle ratio) 5: Split (break a kit SKU into its component SKUs) 6: Disposal (destroy / scrap inventory) 7: Photo (warehouse takes photos of the item for archival) 8: Repackaging (re-pack, replace outer carton, add cushioning, repair damaged packaging, etc.) 9: Cycle Count (periodic spot count to reconcile inventory quantities) 10: Label (apply additional labels such as FNSKU, hazmat label, Made-in country-of-origin label, etc.)	optional	integer
query	status_id	Status id (VAS created via API goes directly to `Review` — it never sits in Draft, so the API does not accept `1`). Overall flow: `Review (2)` → `Pending (3)` → `Open (4)` → `In Progress (5)` → `Billing Audit (6)` → `Completed (7)`; `Cancelled (8)` can be triggered from any state up to and including `Open`. Available Values: 2: Review — initial state after VAS creation; queued for warehouse review 3: Pending — review passed; waiting for the linked prerequisite (such as the linked ASN being received) to complete; VAS with no prerequisite (`inventory_source = 1 On Hand`) skips this state and goes directly to `Open` 4: Open — all prerequisites ready; the warehouse can start work (the cancellation window ends here; cancellation is no longer allowed afterwards) 5: In Progress — warehouse is actively working 6: Billing Audit — work completed; billing under review 7: Completed — fully finished; fees have been posted (the response field `fees` returns detailed line items only in this state) 8: Cancelled — cancelled	optional	integer
query	warehouse_id	Warehouse id	optional	integer
query	asn_id	Filter by linked ASN	optional	integer
query	scheduled_at_from	SLA scheduled start time — from Timezone: Pacific Standard Time	optional	datetime
query	scheduled_at_to	SLA scheduled start time — to Timezone: Pacific Standard Time	optional	datetime
query	created_at_from	Created time — from Timezone: Pacific Standard Time	optional	datetime
query	created_at_to	Created time — to Timezone: Pacific Standard Time	optional	datetime
query	updated_at_from	Updated time — from Timezone: Pacific Standard Time	optional	datetime
query	updated_at_to	Updated time — to Timezone: Pacific Standard Time	optional	datetime
query	next_token	Token for the next page	optional	string

Request Example

GET /api/v202608/vas?api=index.by-default&vas_type=2&status_id=5&warehouse_id=100&created_at_from=2026-08-01%2000:00:00

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
vas_id	VAS id	integer
title	Title	string
description	Description / reason	string
vas_type	VAS type id: 1: General (generic handling; the actual work is described in `description`; the only type that supports `inventory_source = 5 Conditioned`) 2: Relabel / Change SKU (relabel / change SKU) 3: Remeasure (re-measure dimensions and weight) 4: Assembly (assemble multiple SKUs into a new kit SKU per bundle ratio) 5: Split (break a kit SKU into its component SKUs) 6: Disposal (destroy / scrap inventory) 7: Photo (photo archival) 8: Repackaging (re-pack) 9: Cycle Count (periodic spot count) 10: Label (apply additional labels such as FNSKU / hazmat label / country-of-origin label)	integer
vas_type_name	VAS type display name	string
status_id	Status id	integer
status	VAS processing status (VAS created via API goes directly to `Review` — it never sits in Draft, so Draft is not listed in the API docs). Overall flow: `Review` → `Pending` → `Open` → `In Progress` → `Billing Audit` → `Completed`; `Cancelled` can be triggered from any state up to and including `Open`: Review: initial state after VAS creation; warehouse review in progress Pending: review passed; waiting for the linked prerequisite (such as the linked ASN being received) to complete; once the prerequisite is ready it automatically advances to `Open`. VAS with no prerequisite (e.g. `inventory_source = On Hand`) skips `Pending` and goes directly to `Open` when the review passes Open: all prerequisites ready; the warehouse can start work (the cancellation window ends here) In Progress: warehouse is actively working Billing Audit: work completed; billing under review Completed: fully finished; fees have been posted (the response field `fees` returns detailed line items only in this state) Cancelled: cancelled	string
warehouse_id	Warehouse id	integer
warehouse_name	Warehouse name	string
inventory_source	Inventory source id: from which pool of inventory this VAS draws. 1: On Hand — deducted from existing sellable inventory in the warehouse; no prerequisite; can enter `Open` immediately 3: ASN — deducted from the inventory received via the linked ASN; must wait for the ASN receipt to complete; while the linked ASN has not been received the VAS stays in `Pending` 5: Conditioned — deducted from non-New inventory (Damaged / awaiting inspection / already put-away, etc.); supported only when `vas_type = 1 (General)`	integer
inventory_source_name	Inventory source display name	string
scheduled_start_time	SLA scheduled start time Timezone: Pacific Standard Time	datetime
scheduled_finish_time	SLA scheduled finish time Timezone: Pacific Standard Time	datetime
actual_start_time	Actual start time Timezone: Pacific Standard Time	datetime
actual_finish_time	Actual finish time Timezone: Pacific Standard Time	datetime
vas_items	Array of SKU line items	array
linked_asn_ids	Array of linked ASN ids	array of integer
docs	Array of client-side uploaded attachments	array
photos	Array of warehouse-side uploaded photo URLs (read-only, plain URL array)	array of string
fees	Array of fees (populated only in the Completed state)	array
create_time	Created time Timezone: Pacific Standard Time	datetime
update_time	Updated time Timezone: Pacific Standard Time	datetime

vas_items sub-structure

Name	Description	Schema
customer_sku	Customer SKU	string
qty	Quantity	integer

docs sub-structure

Name	Description	Schema
doc_id	Attachment id	integer
type_id	Attachment type id: 1: Packing Slip (item list shipped with the goods for the receiver to verify) 2: BOL (Bill of Lading — the LTL carrier's shipping document) 3: Carton Label (carton mark applied to the outside of each carton) 4: Pallet Label 5: Shipping Label (small-parcel shipping label, used for SPD) 6: Other	integer
doc_name	File name	string
ext	Extension	string
url	Full attachment URL: the domain belongs to ShipSage (`.shipsage.com` / `.shipsage.cn` / `.gaatu.com` / `.jootop.com`) and the path starts with `/uploads/`. Access: files with `owner = Merchant` (uploaded by the customer, stored under company 0) are served by the public file route — anyone holding the URL can download it directly (so the warehouse can print it days later); files with `owner = ShipSage` (uploaded by the warehouse, stored under the warehouse company directory) require an access token and go through the authenticated route. Validity: long-lived, never expires	string
owner	`Merchant` / `ShipSage`	string
created_at	Uploaded time Timezone: Pacific Standard Time	datetime

fees sub-structure

Name	Description	Schema
fee_name	Fee name	string
balance_type	Settlement type	string
price	Unit price	decimal
qty	Quantity	decimal
total_fee	Total fee (`price × qty`)	decimal
description	Description	string

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "vas_id": 15216,
                "title": "换标 A → B",
                "description": "SKU 品牌方要求换标",
                "vas_type": 2,
                "vas_type_name": "Relabel / Change SKU",
                "status_id": 5,
                "status": "In Progress",
                "warehouse_id": 100,
                "warehouse_name": "SG-MDW1",
                "inventory_source": 1,
                "inventory_source_name": "On Hand",
                "scheduled_start_time": "2026-08-15 09:00:00",
                "scheduled_finish_time": "2026-08-15 17:00:00",
                "actual_start_time": "2026-08-15 09:30:00",
                "actual_finish_time": null,
                "vas_items": [
                    { "customer_sku": "CUS-SKU-001", "qty": 200 }
                ],
                "linked_asn_ids": [],
                "docs": [
                    {
                        "doc_id": 7001, "type_id": 6, "doc_name": "authorization.pdf",
                        "ext": "pdf", "url": "https://cdn.shipsage.com/vas/authorization.pdf",
                        "owner": "Merchant", "created_at": "2026-08-14 10:00:00"
                    }
                ],
                "photos": [],
                "fees": [],
                "create_time": "2026-08-14 09:00:00",
                "update_time": "2026-08-15 09:30:00"
            }
        ],
        "next_token": null
    }
}

POST /api/v202608/vas (Create VAS)

Only one VAS is created per call. After creation, the VAS status is Review (Draft is skipped).

Request

Params

Type	Name	Description	Required/Optional	Schema
query	api	API type Available Values: store.by-default	required	enum
body	title	VAS title	required	string
body	description	Description / reason	required	string
body	vas_type	VAS type Available Values: 1: General (generic handling; the actual work is described in `description`; the only type that supports `inventory_source = 5 Conditioned`; when combined with Conditioned, `vas_items` may be empty) 2: Relabel / Change SKU (replace the item's outer label and reassign SKU ownership at the same time — the two actions are two facets of the same operation) 3: Remeasure (re-measure item dimensions and weight; when `qty` is omitted or ≤ 0 it defaults to 1, because remeasure only applies to a single piece) 4: Assembly (assemble multiple SKUs into a new kit SKU per bundle ratio; `customer_sku` must be a kit product) 5: Split (break a kit SKU into its component SKUs; `customer_sku` must be a kit product) 6: Disposal (destroy / scrap inventory) 7: Photo (warehouse takes photos of the item for archival) 8: Repackaging (re-pack, replace outer carton, add cushioning, repair damaged packaging, etc.) 9: Cycle Count (periodic spot count to reconcile inventory quantities; `qty` is force-zeroed server-side — any value sent is ignored) 10: Label (apply additional labels such as FNSKU / hazmat label / country-of-origin label, etc.)	required	enum
body	warehouse_id	Warehouse id	required	integer
body	inventory_source	Inventory source: from which pool of inventory this VAS draws. Available Values: 1: On Hand (default) — deducted from existing sellable inventory in the warehouse 3: ASN — deducted from the inventory received via the linked ASN; must wait for the ASN receipt to complete (while the linked ASN has not been received, the VAS stays in `Pending`) 5: Conditioned — deducted from non-New inventory (Damaged / awaiting inspection / already put-away, etc.); supported only when `vas_type = 1 (General)`	optional (default 1)	enum
body	asn_id	Linked ASN id (required when `inventory_source = 3`; the ASN must exist)	conditionally required	integer
body	vas_items	Array of SKU line items (see the coupling rules below)	conditionally required	array

Coupling validation:

inventory_source = 5 (Conditioned) can only be combined with vas_type = 1 (General)
When vas_type = 1 + inventory_source = 5, vas_items may be empty; for every other combination it is required
When vas_type = 4 (Assembly) / 5 (Split), customer_sku must be a kit product

vas_items sub-structure

Name	Description	Required/Optional	Schema
customer_sku	Customer SKU	required	string
qty	Quantity (see rules below)	conditionally required	integer

qty rules:

vas_type = 9 (Cycle Count): force-zeroed server-side — any value sent is ignored
vas_type = 3 (Remeasure): defaults to 1 when omitted or <= 0 (remeasure applies to 1 pcs only)
Other types: required and > 0

Note: Attachments are not attached at creation time — they use the dedicated POST /vas-docs endpoint.

Request Example (Relabel type)

{
    "title": "换标 A → B",
    "description": "SKU 品牌方要求换标",
    "vas_type": 2,
    "warehouse_id": 100,
    "inventory_source": 1,
    "vas_items": [
        { "customer_sku": "CUS-SKU-001", "qty": 200 }
    ]
}

Request Example (Disposal type, disposed from an ASN)

{
    "title": "销毁 - 客户主动退运",
    "description": "客户临时退运，销毁处理",
    "vas_type": 6,
    "warehouse_id": 100,
    "inventory_source": 3,
    "asn_id": 88888,
    "vas_items": [
        { "customer_sku": "CUS-SKU-001", "qty": 50 }
    ]
}

Request Example (General + Conditioned, `vas_items` may be omitted)

{
    "title": "General 通用作业",
    "description": "由仓库现场判断需要的操作",
    "vas_type": 1,
    "warehouse_id": 100,
    "inventory_source": 5
}

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
vas_id	Id of the newly created VAS	integer
status	VAS status string (typically `Review`)	string

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "vas_id": 15216,
        "status": "Review"
    }
}

DELETE /api/v202608/vas/{vas_id} (Cancel VAS)

Cancellation does not physically delete the record — the VAS is kept in the Cancelled state and remains queryable. Cancellation is performed atomically: it releases the reserved On Hand inventory, returns the linked ASN quantities, cancels any linked Transfer, flips the status, and writes an operation log.

Allowed states: Review / Pending / Open. A VAS that is already Cancelled or has entered the work stream cannot be cancelled.

Request

Params

Type	Name	Description	Required/Optional	Schema
path	vas_id	The VAS id to be cancelled	required	integer
query	api	API type Available Values: destroy.by-default	required	enum

Request Example

DELETE /api/v202608/vas/15216?api=destroy.by-default

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
vas_id	VAS id	integer
status	Status (`Cancelled`)	string
cancelled_at	Cancellation timestamp Timezone: Pacific Standard Time	datetime

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "vas_id": 15216,
        "status": "Cancelled",
        "cancelled_at": "2026-08-14 15:30:00"
    }
}

GET /api/v202608/vas-docs (Retrieve VAS attachments)

vas_id is required. Attachments of any VAS state (including Cancelled) can be read.

Request

Params

Type	Name	Description	Required/Optional	Schema
query	api	API type Available Values: index.by-default	required	enum
query	vas_id	Target VAS id	required	integer
query	type_id	Filter by attachment type Available Values: 1: Packing Slip (item list shipped with the goods for the receiver to verify) 2: BOL (Bill of Lading) 3: Carton Label (carton mark) 4: Pallet Label 5: Shipping Label (small-parcel shipping label) 6: Other	optional	integer
query	next_token	Token for the next page	optional	string

Request Example

GET /api/v202608/vas-docs?api=index.by-default&vas_id=15216

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
doc_id	Attachment id	integer
vas_id	The VAS id this attachment belongs to	integer
type_id	Attachment type id: 1: Packing Slip (item list shipped with the goods for the receiver to verify) 2: BOL (Bill of Lading — the LTL carrier's shipping document) 3: Carton Label (carton mark applied to the outside of each carton) 4: Pallet Label 5: Shipping Label (small-parcel shipping label, used for SPD) 6: Other	integer
doc_name	File name	string
ext	Extension	string
url	Full attachment URL: the domain belongs to ShipSage (`.shipsage.com` / `.shipsage.cn` / `.gaatu.com` / `.jootop.com`) and the path starts with `/uploads/`. Access: files with `owner = Merchant` (uploaded by the customer, stored under company 0) are served by the public file route — anyone holding the URL can download it directly (so the warehouse can print it days later); files with `owner = ShipSage` (uploaded by the warehouse, stored under the warehouse company directory) require an access token and go through the authenticated route. Validity: long-lived, never expires	string
owner	`Merchant` (uploaded by the customer) / `ShipSage` (uploaded by the warehouse)	string
created_at	Uploaded time Timezone: Pacific Standard Time	datetime

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "doc_id": 7001,
                "vas_id": 15216,
                "type_id": 6,
                "doc_name": "authorization.pdf",
                "ext": "pdf",
                "url": "https://cdn.shipsage.com/vas/authorization.pdf",
                "owner": "Merchant",
                "created_at": "2026-08-14 10:00:00"
            }
        ],
        "next_token": null
    }
}

POST /api/v202608/vas-docs (Upload VAS attachment)

Uploads one attachment per call. Writes are not allowed only in the Cancelled state. The URL must come from a ShipSage file upload endpoint.

Request

Params

Type	Name	Description	Required/Optional	Schema
query	api	API type Available Values: store.by-default	required	enum
body	vas_id	Target VAS id	required	integer
body	type_id	Attachment type id Available Values: 1: Packing Slip (item list shipped with the goods for the receiver to verify) 2: BOL (Bill of Lading — the LTL carrier's shipping document) 3: Carton Label (carton mark applied to the outside of each carton) 4: Pallet Label 5: Shipping Label (small-parcel shipping label, used for SPD) 6: Other	required	enum
body	url	File URL — must be a URL previously returned by the ShipSage file upload endpoint `POST /api/v202206/files?api=store.by-upload`; no external / third-party URL is accepted. Validation rules: 1. The domain must belong to ShipSage (`shipsage.com` / `shipsage.cn` / `gaatu.com` / `jootop.com` and their subdomains) 2. The path must start with `/uploads/` 3. The target file must actually exist (the system verifies in real time that the file is reachable in storage) 4. Query String and Fragment are stripped server-side (signed links expire, so persisting them is not allowed) 5. Stored as a relative path in the database, up to 255 characters Background: these attachments are printed by the warehouse days later (printing BOLs, applying carton marks). If they pointed to an external server the link might no longer be reachable at that time — hence the requirement that all attachments be uploaded to ShipSage storage first	required	string
body	doc_name	File name (if omitted, derived from the URL basename; up to 255 characters)	optional	string

Note: owner for client-uploaded attachments is always Merchant.

Request Example

{
    "vas_id": 15216,
    "type_id": 6,
    "url": "https://cdn.shipsage.com/vas/authorization.pdf",
    "doc_name": "authorization.pdf"
}

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
doc_id	New attachment id	integer
vas_id	VAS id	integer
type_id	Attachment type id (same values as the request body `type_id` above)	integer
doc_name	File name	string
url	Full attachment URL: the domain belongs to ShipSage (`.shipsage.com` / `.shipsage.cn` / `.gaatu.com` / `.jootop.com`), the path starts with `/uploads/`, and it is long-lived	string

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "doc_id": 7002,
        "vas_id": 15216,
        "type_id": 1,
        "doc_name": "picking_slip.pdf",
        "url": "https://cdn.shipsage.com/vas/picking_slip.pdf"
    }
}

DELETE /api/v202608/vas-docs/{doc_id} (Delete VAS attachment)

Only attachments uploaded by your own company (owner = Merchant) may be deleted; warehouse-uploaded attachments cannot be deleted. Attachments also cannot be modified when the VAS has been cancelled.

Request

Params

Type	Name	Description	Required/Optional	Schema
path	doc_id	Attachment id	required	integer
query	api	API type Available Values: destroy.by-default	required	enum

Request Example

DELETE /api/v202608/vas-docs/500123?api=destroy.by-default

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
doc_id	Attachment id	integer
vas_id	VAS id	integer
doc_name	File name	string

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "doc_id": 7002,
        "vas_id": 15216,
        "doc_name": "picking_slip.pdf"
    }
}

Endpoints

Header

GET /api/v202608/vas (Retrieve VAS list)

Request

Params

Request Example

Response

Data Properties

vas_items sub-structure

docs sub-structure

fees sub-structure

Response Example

POST /api/v202608/vas (Create VAS)

Request

Params

vas_items sub-structure

Request Example (Relabel type)

Request Example (Disposal type, disposed from an ASN)

Request Example (General + Conditioned, vas_items may be omitted)

Response

Data Properties

Response Example

DELETE /api/v202608/vas/{vas_id} (Cancel VAS)

Request

Params

Request Example

Response

Data Properties

Response Example

GET /api/v202608/vas-docs (Retrieve VAS attachments)

Request

Params

Request Example

Response

Data Properties

Response Example

POST /api/v202608/vas-docs (Upload VAS attachment)

Request

Params

Request Example

Response

Data Properties

Response Example

DELETE /api/v202608/vas-docs/{doc_id} (Delete VAS attachment)

Request

Params

Request Example

Response

Data Properties

Response Example

Request Example (General + Conditioned, `vas_items` may be omitted)