Create scan form for labels

Overview and use cases

Create a scan form (also called a shipping manifest) that groups multiple labels so the carrier can scan a single document at pickup. The scan form consolidates shipments using tracking numbers for end-of-day (EOD) pickup and processing. Scan forms are generated for labels that ship on the seller-specified ship date (shipOnDate). Currently, only USPS supports scan forms.

Use this endpoint to:

Generate a daily USPS manifest for pickup
Consolidate up to 200 shipments into a single scan form
Support EOD workflows and carrier handoff processes
Enable automated scan form creation as part of shipping operations

Before you start

You must be onboarded for Ship With Walmart (SWW).
You need a valid access token for authentication.
Keep a unique scanFormId for each scan form you create (used for idempotency; reusing it after success can return 409).

Endpoint

POST https://marketplace.walmartapis.com/v3/shipping/scan-form

Request sample

curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/shipping/scan-form' \ --header 'WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6' \ --header 'WM_MARKET: US' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'WM_SEC.ACCESS_TOKEN: <Your_access_token>' \ --header 'WM_GLOBAL_VERSION: 3.1' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "scanFormId": "SF-20250823-CA-001", "carrierName": "USPS", "shipOnDate": "2025-08-23", "fromAddress": { "contactName": "John Doe", "companyName": "Walmart", "addressLine1": "1375 Crossman Ave", "addressLine2": "Suite 100", "city": "Sunnyvale", "state": "CA", "postalCode": "94089", "country": "US", "phone": "6172012456", "email": "[email protected]" }, "trackingNumbers": [ "100044481029", "100044481030" ], "documentFormat": "PDF" }'

import requests url = "https://marketplace.walmartapis.com/v3/shipping/scan-form" headers = { "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_MARKET": "US", "WM_SVC.NAME": "Walmart Marketplace", "WM_SEC.ACCESS_TOKEN": "<Your_access_token>", "WM_GLOBAL_VERSION": "3.1", "Accept": "application/json", "Content-Type": "application/json",
} payload = { "scanFormId": "SF-20250823-CA-001", "carrierName": "USPS", "shipOnDate": "2025-08-23", "fromAddress": { "contactName": "John Doe", "companyName": "Walmart", "addressLine1": "1375 Crossman Ave", "addressLine2": "Suite 100", "city": "Sunnyvale", "state": "CA", "postalCode": "94089", "country": "US", "phone": "6172012456", "email": "[email protected]" }, "trackingNumbers": [ "100044481029", "100044481030" ], "documentFormat": "PDF"
} response = requests.post(url, headers=headers, json=payload) print(response.status_code)
print(response.text)

Modify your code

You can customize the request to generate scan forms for different EOD batches:

Update scanFormId to a deterministic value so retries do not create duplicates (idempotency behavior).
Update shipOnDate (format yyyy-MM-dd).
Update fromAddress to match the pickup origin address used for the scan form.
Update trackingNumbers to include the tracking numbers for the EOD batch (1 - 200).
Update documentFormat to your preferred output format (description implies PDF, ZPL, PNG, BLOB).

Example customization

{ "scanFormId": "SF-20250824-CA-001", "carrierName": "USPS", "shipOnDate": "2025-08-24", "fromAddress": { "contactName": "Pickup Desk", "companyName": "My Warehouse", "addressLine1": "123 Warehouse Way", "city": "Sunnyvale", "state": "CA", "postalCode": "94089", "country": "US", "phone": "5551234567" }, "trackingNumbers": ["100044481029", "100044481030", "100044481031"], "documentFormat": "PDF"
}

Response sample

{ "data": { "manifestId": "599010122", "status": "SUCCESS" }
}

Results

A successful response returns:

manifestId: store this value to download the scan form document
status: outcome of the create request (spec indicates SUCCESS)

Error handling

Status code	Description	Remediation
400	Invalid request	Validate required fields, ensure `trackingNumbers` is not empty, and confirm date/address formats.
409	Scan form already exists for `scanFormId`	Treat as idempotency conflict. Do not create another scan form; retrieve the existing scan form using the previously returned `manifestId`.
429	Rate limit exceeded	Retry with backoff; reduce request rate. Refer to the rate limiting guide for throttling limits.

Best practices

Use deterministic scanFormId values for safe retries.
Persist {scanFormId, manifestId} in your EOD run metadata.
Split into multiple scan forms if you exceed 4,000 tracking numbers.
Use tracking numbers that correspond to the same ship date (shipOnDate) and origin address (fromAddress) to avoid carrier pickup issues..
Create scan forms once per ship date and pickup location to avoid operational confusion.

Next steps

After creating a scan form:

Download the scan form document using GET /v3/shipping/scan-form?manifestId=....
Integrate scan form creation into scheduled EOD closeout workflows.