---
updatedAt: 2026-06-22T19:19:50.000Z
---

# Create scan form for labels

This API generates a scan form using the provided tracking numbers. The scan form is a consolidated document that contains all the tracking numbers and shipping details for the packages being shipped out on a particular day. It is used by carriers to verify and process the shipments during pickup and delivery. Currently, only USPS supports scan forms.

**Idempotency:** `scanFormId` acts as a natural idempotency key — the client supplies it in the request body before the call. Submitting a second POST with a `scanFormId` that was already successfully processed returns `409 Conflict`; no duplicate scan form is created. On network failure or timeout, clients may safely retry using the same `scanFormId`. This guarantee is critical for EOD automation — a duplicate manifest can cause carrier processing errors and shipment delays.

**Rate Limits:** This endpoint allows 100 requests per minute. Exceeding this limit returns a `429 Too Many Requests` response. See the [Rate Limiting guide](https://developer.walmart.com/us-marketplace/docs/rate-limiting) for full details. The response includes `x-current-token-count` (remaining requests in the current window) and `X-Next-Replenishment-Time` (when the token count next increases).

**Sandbox:** Use base URL `https://sandbox.walmartapis.com`. The sandbox accepts test tracking numbers and returns a synthetic `manifestId` (e.g. `SANDBOX-12345`). Use that `manifestId` with the GET endpoint to retrieve the stub scan form document.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Ship With Walmart",
    "version": "1.0",
    "description": "The Ship With Walmart (SWW) APIs enables walmart.com sellers to buy shipping at competitively discounted rates directly from Walmart to ship their goods to US customers."
  },
  "x-readme": {
    "samples-languages": [
      "shell"
    ],
    "proxy-enabled": false
  },
  "servers": [
    {
      "url": "https://marketplace.walmartapis.com",
      "description": "Production URL"
    },
    {
      "url": "https://sandbox.walmartapis.com",
      "description": "Sandbox URL"
    }
  ],
  "security": [
    {
      "accessToken": []
    }
  ],
  "paths": {
    "/v3/shipping/scan-form": {
      "post": {
        "tags": [
          "Ship With Walmart"
        ],
        "summary": "Create scan form for labels",
        "description": "This API generates a scan form using the provided tracking numbers. The scan form is a consolidated document that contains all the tracking numbers and shipping details for the packages being shipped out on a particular day. It is used by carriers to verify and process the shipments during pickup and delivery. Currently, only USPS supports scan forms.\n\n**Idempotency:** `scanFormId` acts as a natural idempotency key — the client supplies it in the request body before the call. Submitting a second POST with a `scanFormId` that was already successfully processed returns `409 Conflict`; no duplicate scan form is created. On network failure or timeout, clients may safely retry using the same `scanFormId`. This guarantee is critical for EOD automation — a duplicate manifest can cause carrier processing errors and shipment delays.\n\n**Rate Limits:** This endpoint allows 100 requests per minute. Exceeding this limit returns a `429 Too Many Requests` response. See the [Rate Limiting guide](https://developer.walmart.com/us-marketplace/docs/rate-limiting) for full details. The response includes `x-current-token-count` (remaining requests in the current window) and `X-Next-Replenishment-Time` (when the token count next increases).\n\n**Sandbox:** Use base URL `https://sandbox.walmartapis.com`. The sandbox accepts test tracking numbers and returns a synthetic `manifestId` (e.g. `SANDBOX-12345`). Use that `manifestId` with the GET endpoint to retrieve the stub scan form document.",
        "x-stability": "beta",
        "operationId": "scanForm",
        "security": [
          {
            "accessToken": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "WM_CONSUMER.CHANNEL.TYPE",
            "description": "A unique ID to identify the consumer request by channel. Use the Consumer Channel Type received during onboarding.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "WM_QOS.CORRELATION_ID",
            "description": "A unique ID that identifies each API call and is used to track and debug issues. Use a randomly generated GUID for this ID.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "b3261d2d-028a-4ef7-8602-633c23200af6"
          },
          {
            "in": "header",
            "name": "WM_SVC.NAME",
            "description": "Specifies the name of the Walmart service being called.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Walmart Marketplace"
          },
          {
            "in": "header",
            "name": "Accept",
            "description": "Only supported media type: application/json.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "application/json"
          }
        ],
        "requestBody": {
          "description": "Request payload for creating a scan form.",
          "content": {
            "application/json": {
              "schema": {
                "required": [
                  "scanFormId",
                  "carrierName",
                  "shipOnDate",
                  "fromAddress",
                  "trackingNumbers",
                  "documentFormat"
                ],
                "type": "object",
                "properties": {
                  "scanFormId": {
                    "type": "string",
                    "description": "Client-generated unique identifier for this scan form. Acts as a natural idempotency key — submitting a second POST with the same scanFormId returns 409 Conflict without creating a duplicate. Use a deterministic value (e.g., sellerId + shipOnDate + shipNode) to enable safe retries on network failure."
                  },
                  "carrierName": {
                    "type": "string",
                    "description": "Carrier short name for the scan form request. This value maps to shortName from the supported carriers API response."
                  },
                  "shipOnDate": {
                    "type": "string",
                    "description": "Ship-on date for the scan form. This is the date when the shipment is scheduled for carrier pickup. Format: yyyy-MM-dd."
                  },
                  "fromAddress": {
                    "required": [
                      "addressLine1",
                      "city",
                      "contactName",
                      "country",
                      "phone",
                      "postalCode",
                      "state"
                    ],
                    "type": "object",
                    "properties": {
                      "contactName": {
                        "type": "string",
                        "x-pii": true,
                        "description": "Contact name for the origin address."
                      },
                      "companyName": {
                        "type": "string",
                        "description": "Company name for the origin address."
                      },
                      "addressLine1": {
                        "type": "string",
                        "description": "First line of the origin street address."
                      },
                      "addressLine2": {
                        "type": "string",
                        "description": "Second line of the origin street address, such as suite or unit."
                      },
                      "city": {
                        "type": "string",
                        "description": "Origin city name."
                      },
                      "state": {
                        "type": "string",
                        "description": "Origin state or province. Use the region code when available. For example, CA, AK."
                      },
                      "postalCode": {
                        "type": "string",
                        "description": "Origin postal or ZIP code."
                      },
                      "country": {
                        "type": "string",
                        "description": "Origin country code. Use a two-letter code. For example, US, CN, IN."
                      },
                      "phone": {
                        "type": "string",
                        "x-pii": true,
                        "description": "Origin contact phone number."
                      },
                      "email": {
                        "type": "string",
                        "x-pii": true,
                        "description": "Origin contact email address."
                      }
                    },
                    "description": "Origin address used for the scan form."
                  },
                  "trackingNumbers": {
                    "type": "array",
                    "maxItems": 200,
                    "minItems": 1,
                    "description": "List of tracking numbers to include in the scan form. Maximum 200 tracking numbers per scan form (USPS limit).",
                    "items": {
                      "type": "string"
                    }
                  },
                  "carrierServiceType": {
                    "type": "string",
                    "description": "Carrier service type. This value maps to serviceTypes.name from the shipping estimates API response."
                  },
                  "documentFormat": {
                    "type": "string",
                    "description": "Requested scan form output format. Allowed values: PDF, ZPL, PNG, BLOB. Default is PDF."
                  }
                }
              },
              "examples": {
                "sample1": {
                  "value": {
                    "scanFormId": "string",
                    "carrierName": "USPS",
                    "shipOnDate": "2025-08-23",
                    "fromAddress": {
                      "contactName": "John Doe",
                      "companyName": "Walmart",
                      "addressLine1": "1375 Crossman Ave",
                      "addressLine2": "string",
                      "city": "Sunnyvale",
                      "state": "CA",
                      "postalCode": "63116",
                      "country": "US",
                      "phone": "6172012456",
                      "email": ""
                    },
                    "trackingNumbers": [
                      "100044481029",
                      "100044481030"
                    ],
                    "documentFormat": "PDF"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Maximum number of requests allowed in the current rate-limit window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Number of requests remaining in the current rate-limit window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "Unix timestamp (seconds) at which the current rate-limit window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "manifestId": {
                          "type": "string",
                          "description": "Manifest ID returned by the create scan form API. Use this value to download the scan form or for future reference."
                        },
                        "status": {
                          "type": "string",
                          "description": "Status of the scan form request. Example: SUCCESS."
                        }
                      },
                      "description": "Response payload for the operation."
                    }
                  }
                },
                "examples": {
                  "sample1": {
                    "value": {
                      "data": {
                        "manifestId": "599010122",
                        "status": "SUCCESS"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid operation",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                },
                "examples": {
                  "sample1": {
                    "value": {
                      "type": "https://marketplace.walmart.com/errors/invalid-scan-form",
                      "title": "Invalid Scan Form Request",
                      "status": 400,
                      "detail": "trackingNumbers must not be empty.",
                      "instance": "/v3/shipping/scan-form"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict — a scan form with the given scanFormId already exists. No duplicate is created. Retrieve the existing scan form using the GET endpoint with the previously returned manifestId.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                },
                "examples": {
                  "sample1": {
                    "value": {
                      "type": "https://marketplace.walmart.com/errors/scan-form-already-exists",
                      "title": "Scan Form Already Exists",
                      "status": 409,
                      "detail": "A scan form with scanFormId 'SF-20240513-001' already exists for this seller.",
                      "instance": "/v3/shipping/scan-form"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "description": "Problem details for HTTP APIs as defined by RFC 9457. This is the standard error envelope used by all new Ship With Walmart endpoints.",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI that identifies the problem type.",
            "example": "https://marketplace.walmart.com/errors/invalid-ship-date"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type.",
            "example": "Invalid ship date"
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "The HTTP status code returned by the origin server for this occurrence.",
            "example": 400
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation of the problem.",
            "example": "Input date format is incorrect. Expected MM/dd/yyyy."
          },
          "instance": {
            "type": "string",
            "description": "URI reference identifying the specific occurrence of the problem.",
            "example": "/v3/shipping/ship-nodes/NODE-001/ship-on-date"
          },
          "code": {
            "type": "string",
            "description": "A Walmart legacy error response code. This code is a backwards compatible alert and has a runbook lookup.",
            "example": "LS-4010"
          }
        }
      }
    },
    "securitySchemes": {
      "accessToken": {
        "type": "apiKey",
        "in": "header",
        "name": "WM_SEC.ACCESS_TOKEN",
        "description": "Access token from POST /v3/token (client_credentials grant)."
      }
    }
  }
}
```