---
updatedAt: 2026-04-12T09:29:44.000Z
---

# Submit a claim

Creates a shipment-protection claim. Send multipart/form-data with files, documentTypes, and payload.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Claims",
    "version": "1.0",
    "description": "Endpoints for creating and tracking Ship with Walmart (SWW) shipment-protection claims."
  },
  "x-readme": {
    "samples-languages": [
      "shell"
    ],
    "proxy-enabled": false,
    "explorer-enabled": true
  },
  "servers": [
    {
      "url": "https://marketplace.walmartapis.com",
      "description": "Production URL"
    },
    {
      "url": "https://sandbox.walmartapis.com",
      "description": "Sandbox URL"
    }
  ],
  "paths": {
    "/v3/claims/shipment-protection/claim": {
      "post": {
        "tags": [
          "Shipment Protection"
        ],
        "summary": "Submit a claim",
        "description": "Creates a shipment-protection claim. Send multipart/form-data with files, documentTypes, and payload.",
        "operationId": "submitClaim",
        "parameters": [
          {
            "name": "WM_SEC.ACCESS_TOKEN",
            "in": "header",
            "description": "The access token retrieved in the Token API call.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM....."
          },
          {
            "name": "WM_CONSUMER.CHANNEL.TYPE",
            "in": "header",
            "description": "A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "WM_QOS.CORRELATION_ID",
            "in": "header",
            "description": "A unique ID which 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"
          },
          {
            "name": "WM_SVC.NAME",
            "in": "header",
            "description": "Walmart service name—for Marketplace APIs simply use `Walmart Service Name` or the service identifier provided by Walmart.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Walmart Service Name"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "files",
                  "documentTypes",
                  "payload"
                ],
                "properties": {
                  "files": {
                    "type": "array",
                    "description": "One or more supporting files (images, PDFs, etc.).",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  },
                  "documentTypes": {
                    "type": "array",
                    "description": "Maps each uploaded file to its document category.",
                    "items": {
                      "type": "object",
                      "required": [
                        "fileName",
                        "type"
                      ],
                      "properties": {
                        "fileName": {
                          "type": "string",
                          "description": "Original file name as uploaded."
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "PROOF_OF_DAMAGED_ITEM",
                            "INVOICE",
                            "OTHER",
                            "PPOD"
                          ],
                          "description": "Document category."
                        }
                      },
                      "description": "Object describing a single uploaded document."
                    }
                  },
                  "payload": {
                    "type": "object",
                    "description": "Claim details.",
                    "required": [
                      "purchaseOrderNo",
                      "purchaseOrderLineNo",
                      "salesOrderNo",
                      "salesOrderLineNo",
                      "fulfillerLineId",
                      "quantity",
                      "returnOrderId",
                      "claimType"
                    ],
                    "properties": {
                      "purchaseOrderNo": {
                        "type": "string",
                        "description": "Marketplace purchase-order number associated with the item in this claim."
                      },
                      "purchaseOrderLineNo": {
                        "type": "string",
                        "description": "Line number within the purchase order that maps to the claimed SKU."
                      },
                      "salesOrderNo": {
                        "type": "string",
                        "description": "Customer sales-order number for the shipment."
                      },
                      "salesOrderLineNo": {
                        "type": "string",
                        "description": "Line number within the sales order that maps to the claimed SKU."
                      },
                      "fulfillerLineId": {
                        "type": "string",
                        "description": "Identifier for the fulfiller’s line item in the warehouse/fulfillment center manifest."
                      },
                      "quantity": {
                        "type": "integer",
                        "format": "int32",
                        "description": "Number of units being claimed for this line."
                      },
                      "returnOrderId": {
                        "type": "string",
                        "description": "Return-order ID that triggered or is linked to the claim."
                      },
                      "claimType": {
                        "type": "string",
                        "enum": [
                          "LIT",
                          "LAD",
                          "DAMAGED"
                        ],
                        "description": "Claim category: LIT (lost in transit), LAD (lost after delivery), or DAMAGED."
                      },
                      "notes": {
                        "type": "string",
                        "description": "Free-form claim notes from the seller."
                      }
                    }
                  }
                },
                "example": {
                  "files": [
                    "file1.jpg",
                    "invoice.pdf"
                  ],
                  "documentTypes": [
                    {
                      "fileName": "file1.jpg",
                      "type": "PROOF_OF_DAMAGED_ITEM"
                    },
                    {
                      "fileName": "invoice.pdf",
                      "type": "INVOICE"
                    }
                  ],
                  "payload": {
                    "purchaseOrderNo": "RAPMOCK1729803026938",
                    "purchaseOrderLineNo": "1",
                    "salesOrderNo": "RAPMOCK1729803026883",
                    "salesOrderLineNo": "1",
                    "fulfillerLineId": "1",
                    "quantity": 3,
                    "returnOrderId": "136900073772361154",
                    "claimType": "DAMAGED",
                    "notes": "Claim submission notes."
                  }
                }
              },
              "encoding": {
                "files": {
                  "contentType": "application/octet-stream"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "data": {
                    "claimNumber": "1000000",
                    "message": "Claim submitted successfully"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "info": {
                            "type": "string"
                          },
                          "code": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "errors": [
                    {
                      "info": "info message",
                      "code": "error code",
                      "description": "detailedMessage",
                      "severity": "ERROR",
                      "category": "DATA etc"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "info": {
                            "type": "string"
                          },
                          "code": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "errors": [
                    {
                      "info": "info message",
                      "code": "error code",
                      "description": "detailedMessage",
                      "severity": "ERROR",
                      "category": "DATA etc"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "info": {
                            "type": "string"
                          },
                          "code": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "errors": [
                    {
                      "info": "info message",
                      "code": "error code",
                      "description": "detailedMessage",
                      "severity": "ERROR",
                      "category": "DATA etc"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```