> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Walmart seller offers

> Return visible Walmart US seller offers using store 1554 (Stockton, California) as the explicit location context. Accepts numeric or alphanumeric product IDs; Canada returns 422 without a charge. Prices and availability are location-dependent, not nationwide. The source does not establish a complete global offer count, so total is null. Unknown conditions, pickup, tax and ratings remain null; price.total is unknown. No pagination or store override.

Costs **5 credits** for a successful live response containing offers. A validated empty response, error, cache hit, or successful idempotent replay costs zero credits. Numeric IDs use one provider read; alphanumeric IDs require an additional product-ID resolution read at the same customer price.

This release supports **Walmart US**, using **store 1554 in Stockton, California** as the explicit location context. The response includes `store_id`, `store_url`, and the source's `shipping_destination`. Prices and stock are location-dependent; they are not nationwide quotes. `country=CA` currently returns an uncharged 422. No store override or pagination is available.

Each item includes a seller, offer ID, source stock label, price, and available return-policy text. `first_party` comes from the source's seller type. `pickup_available`, `condition`, ratings, tax, and shipping remain null when absent. `price.total` remains null because a complete checkout total is unavailable. `return_window_days` is populated only from an explicit day-based policy.

`returned_count` describes the returned offers. The source does not expose a complete global count or continuation, so `total` and `next_cursor` remain null. Products, store context, offer IDs, and formatted/extracted prices must agree; blocked or malformed pages fail instead of returning a fabricated empty list.

Source: [SerpApi Walmart Sellers API](https://serpapi.com/walmart-product-sellers-api), with the existing free search allowance. [Walmart's store page](https://www.walmart.com/store/1554-stockton-ca/) identifies the selected context. This is a snapshot of visible offers, not a stock reservation or a guaranteed purchase price.


## OpenAPI

````yaml GET /walmart/offers
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /walmart/offers:
    get:
      tags:
        - Walmart
      summary: Walmart Offers
      description: >-
        Return visible Walmart US seller offers using store 1554 (Stockton,
        California) as the explicit location context. Accepts numeric or
        alphanumeric product IDs; Canada returns 422 without a charge. Prices
        and availability are location-dependent, not nationwide. The source does
        not establish a complete global offer count, so total is null. Unknown
        conditions, pickup, tax and ratings remain null; price.total is unknown.
        No pagination or store override.
      operationId: get_walmart_offers
      parameters:
        - name: product_id
          in: query
          required: true
          example: '10543894'
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{1,30}$
        - name: country
          in: query
          required: false
          schema:
            type: string
            enum:
              - US
              - CA
          description: >-
            US is supported. CA remains planned and currently returns 422
            without spending.
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            Return visible Walmart US seller offers using store 1554 (Stockton,
            California) as the explicit location context. Accepts numeric or
            alphanumeric product IDs; Canada returns 422 without a charge.
            Prices and availability are location-dependent, not nationwide. The
            source does not establish a complete global offer count, so total is
            null. Unknown conditions, pickup, tax and ratings remain null;
            price.total is unknown. No pagination or store override.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            maxItems: 100
                            items:
                              type: object
                              properties:
                                seller:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    name:
                                      type: string
                                    domain:
                                      type:
                                        - string
                                        - 'null'
                                    url:
                                      type:
                                        - string
                                        - 'null'
                                    price:
                                      type: object
                                      properties:
                                        base:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        tax:
                                          type: 'null'
                                        shipping:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        total:
                                          type: 'null'
                                        currency:
                                          type: string
                                          const: USD
                                      required:
                                        - base
                                        - tax
                                        - shipping
                                        - total
                                        - currency
                                      additionalProperties: false
                                    rating:
                                      type: object
                                      properties:
                                        average:
                                          type: 'null'
                                        count:
                                          type: 'null'
                                      required:
                                        - average
                                        - count
                                      additionalProperties: false
                                    condition:
                                      type:
                                        - string
                                        - 'null'
                                    availability:
                                      type:
                                        - string
                                        - 'null'
                                    annotation:
                                      type:
                                        - string
                                        - 'null'
                                  required:
                                    - id
                                    - name
                                    - domain
                                    - url
                                    - price
                                    - rating
                                    - condition
                                    - availability
                                    - annotation
                                  additionalProperties: false
                                offer_id:
                                  type: string
                                offer_type:
                                  type:
                                    - string
                                    - 'null'
                                first_party:
                                  type:
                                    - boolean
                                    - 'null'
                                pickup_available:
                                  type:
                                    - boolean
                                    - 'null'
                                return_window_days:
                                  type:
                                    - integer
                                    - 'null'
                                  minimum: 0
                                delivery_date:
                                  type:
                                    - string
                                    - 'null'
                              required:
                                - seller
                                - offer_id
                                - offer_type
                                - first_party
                                - pickup_available
                                - return_window_days
                                - delivery_date
                              additionalProperties: false
                          returned_count:
                            type: integer
                            minimum: 0
                          total:
                            type: 'null'
                          dropped:
                            type: integer
                            const: 0
                          next_cursor:
                            type: 'null'
                          product:
                            type: object
                            properties:
                              requested_id:
                                type: string
                              id:
                                type: string
                              title:
                                type: string
                              url:
                                type: string
                            required:
                              - requested_id
                              - id
                              - title
                              - url
                            additionalProperties: false
                          country:
                            type: string
                            const: US
                          store_id:
                            type: string
                            const: '1554'
                          store_url:
                            type: string
                          shipping_destination:
                            type: string
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - returned_count
                          - total
                          - dropped
                          - next_cursor
                          - product
                          - country
                          - store_id
                          - store_url
                          - shipping_destination
                          - source
                          - coverage_note
                        additionalProperties: false
                    required:
                      - data
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.