captapi-com Amazon Shop API

openapi: 3.2.0
info:
  title: Captapi Amazon Shop API
  version: 0.1.0
  summary: Structured public data from social platforms through one REST API.
  description: 'Captapi returns public data (profiles, posts, comments, transcripts, search, ads, commerce) from social platforms as JSON.


    Auth: send your key as `Authorization: Bearer capt_live_...` or `X-API-Key: capt_live_...`. Keys are created by a human at https://captapi.com/dashboard/api-keys.


    Billing: each operation states its cost in `x-credit-cost`. The `X-Captapi-Credits` response header shows what was charged. Failed requests (4xx/5xx) are not billed. `cache=true` serves from the 24h cache, free on a hit where `billedOnCacheHit` is false. Where the price depends on which path served the call, `x-credit-cost.note` gives the full rule and the range we have observed.


    Empty results: on many list and search endpoints a call that ran but found nothing is charged 0 credits (for example an ad-library or profile search with no matches). Where an empty result is still billed, the endpoint description says so; Google Maps business search, for instance, bills its one page because the lookup ran. The `X-Captapi-Credits` header always shows the actual charge.


    Errors: every non-2xx response uses the same envelope, `{ success: false, error: { code, message, retryable } }`. Retry only when `retryable` is true, honouring `Retry-After`.


    Timing: every response carries `Server-Timing: total;dur=`, the total time the request took. Deprecated: the `timings` object some endpoints still return in `data` will be removed from response bodies on 2026-12-17; use the header instead. It is not part of the response schemas below.


    Response schemas are inferred from real captured responses and list the fields seen there plus documented top-level fields. Fields can be null when a platform does not expose them.


    Endpoint list: https://captapi.com/llms-endpoints.txt · Guide for agents: https://captapi.com/llms.txt · MCP: https://captapi.com/mcp.json'
  contact:
    name: Captapi support
    email: support@captapi.com
    url: https://captapi.com
  termsOfService: https://captapi.com/legal/terms
  license:
    name: Captapi Terms of Service
    url: https://captapi.com/legal/terms
servers:
- url: https://api.captapi.com
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Amazon Shop
  description: Public data from Amazon Shop.
paths:
  /v1/amazon-shop/page:
    get:
      operationId: amazon_shop_page
      tags:
      - Amazon Shop
      summary: Amazon Seller Storefront API
      description: 'Third-party seller storefronts (/sp?seller= / /s?me=) — ASIN + canonical /dp URLs, price, badges.


        Pass an Amazon seller storefront URL (/sp?seller=… or /s?me=…) or raw seller ID (e.g. A294P4X9EWVXLJ) and get that merchant''s product listings as clean JSON. Each product includes an extracted ASIN and a canonical https://www.amazon.com/dp/{ASIN} URL (joinable to Amazon''s catalog — not shop/{handle}/getProductDetails/… affiliate paths), plus title, image, price/currency/priceFormatted (omitted when Amazon shows no price), rating/reviews, and isPrime/isBestSeller/isSponsored. Also seller{id,name,url} and cursor pagination (nextCursor/hasMore). platform is amazon. Freshness is envelope fetchedAt. Billing is 1 credit per 16-product storefront page, rounded up from limit — the default limit=20 costs 2 credits. This is not the influencer Amazon Shop surface (amazon.com/shop/{handle}) that returns avatar/socials/lists/curations — those creator vitrines are a different product and return HTTP 400 here.


        Docs: https://captapi.com/apis/amazon-shop-page'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      parameters:
      - name: url
        in: query
        required: true
        description: Amazon seller storefront URL (/sp?seller=… or /s?me=…) or raw seller ID. Not influencer /shop/<handle> pages. The URL platform must match this endpoint's platform. Do not pass cross-platform URLs, e.g. YouTube to TikTok, Instagram to Facebook, LinkedIn to X/Twitter, or Pinterest to Rumble.
        schema:
          type: string
        example: https://www.amazon.com/sp?seller=A294P4X9EWVXLJ
      - name: marketplace
        in: query
        required: false
        description: Amazon marketplace code. Default US.
        schema:
          type: string
          minLength: 2
          maxLength: 5
          default: US
        example: US
      - name: limit
        in: query
        required: false
        description: 'Max products to include (default 20, max 200; 0 = seller metadata only). Billed per 16-product storefront page: ceil(limit / 16) credits, minimum 1 — the default 20 costs 2.'
        schema:
          type: integer
          maximum: 200
          minimum: 0
          default: 20
        example: 20
      - name: cursor
        in: query
        required: false
        description: Pagination cursor from nextCursor (page or page:offset). Leave empty for the first page.
        schema:
          type: string
      - name: cache
        in: query
        required: false
        description: Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh.
        schema:
          type: boolean
          default: false
        example: false
      x-credit-cost:
        credits: 1
        label: 1 credit per 16 products (default limit 20 = 2)
        note: 'Billed per 16-product storefront page: ceil(limit / 16) credits, minimum 1. The default limit=20 spans two pages and costs 2 credits; limit ≤ 16 or limit=0 (seller metadata only) costs 1; limit=200 costs 13.'
        billedOnCacheHit: false
      x-one-liner: Third-party seller storefronts (/sp?seller= / /s?me=) — ASIN + canonical /dp URLs, price, badges.
      responses:
        '200':
          description: Success. The data object for this endpoint.
          headers:
            X-Captapi-Credits:
              $ref: '#/components/headers/Credits'
            X-Captapi-Cache:
              $ref: '#/components/headers/Cache'
            X-Captapi-Request-Id:
              $ref: '#/components/headers/RequestId'
            Server-Timing:
              $ref: '#/components/headers/ServerTiming'
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    const: true
                  data:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: Always "amazon" on this endpoint.
                      url:
                        type: string
                        description: Canonical product page https://www.amazon.com/dp/{ASIN} (not a shop/{handle}/getProductDetails/… affiliate path).
                      marketplace:
                        type: string
                        description: Amazon marketplace code echoed from the request (default US).
                      seller:
                        type: object
                        properties:
                          id:
                            type: string
                            description: Id of this seller item.
                          name:
                            type: string
                            description: Name of this seller item.
                          url:
                            type: string
                            description: Canonical product page https://www.amazon.com/dp/{ASIN} (not a shop/{handle}/getProductDetails/… affiliate path).
                      scrapedAt:
                        type: string
                        description: When this response was collected (ISO 8601). Envelope-level freshness on listings that expose it (e.g. Facebook profile-reels) — not a per-row stamp on Spotify search. facebook/profile-posts uses fetchedAt; there is no scrapedAt twin.
                      totalReturned:
                        type: integer
                        description: Number of items returned in this response.
                      hasMore:
                        type: boolean
                        description: Whether more results are available beyond this page. When true, pass nextCursor to fetch the next page.
                      nextCursor:
                        type: string
                        description: Cursor to pass for the next page of results. May be null when the platform does not expose deep pagination (e.g. some Facebook Ad Library searches).
                      products:
                        type: array
                        items:
                          type: object
                          properties:
                            asin:
                              type: string
                              description: Amazon Standard Identification Number — catalog identity for joins across sellers and marketplaces.
                            title:
                              type: string
                              description: Title of this products item.
                            url:
                              type: string
                              description: Canonical product page https://www.amazon.com/dp/{ASIN} (not a shop/{handle}/getProductDetails/… affiliate path).
                            image:
                              type: string
                              description: Image URL.
                            price:
                              type: number
                              description: Numeric price when Amazon shows one on the card. Omitted with currency/priceFormatted when all three are unavailable.
                            currency:
                              type: string
                              description: ISO currency for price (e.g. USD). Omitted when there is no price.
                            priceFormatted:
                              type: string
                              description: Display price as Amazon printed it (e.g. $49.99). Omitted when there is no price.
                            rating:
                              type: number
                              description: Star rating (out of 5) when the card shows one.
                            reviews:
                              description: Review count printed beside the stars on the storefront card. Omitted when Amazon does not expose a count on that row.
                            isPrime:
                              type: boolean
                              description: 'Is prime. Example: false.'
                            isBestSeller:
                              type: boolean
                              description: 'Is best seller. Example: false.'
                            isSponsored:
                              type: boolean
                              description: 'Is sponsored. Example: false.'
              example:
                success: true
                data:
                  platform: amazon_shop
                  url: https://www.amazon.com/sp?seller=A294P4X9EWVXLJ
                  marketplace: US
                  seller:
                    id: A294P4X9EWVXLJ
                    name: AnkerDirect
                    url: https://www.amazon.com/sp?seller=A294P4X9EWVXLJ
                  scrapedAt: '2026-08-02T16:59:58.250Z'
                  totalReturned: 2
                  hasMore: true
                  nextCursor: '1:5'
                  products:
                  - asin: B08NDYQSXZ
                    title: Anker Charging Dock for Oculus Quest 2, Oculus Certified Charging Station Stand Set, Headset Display Holder and Controller Mount Station with 2 Rechargeable Batteries, USB-C Charger and Cable
                    url: https://www.amazon.com/dp/B08NDYQSXZ
                    image: https://m.media-amazon.com/images/I/61EK9jpDapL._AC_UY218_.jpg
                    price: 49.99
                    currency: USD
                    priceFormatted: $49.99
                    rating: 4.4
                    reviews: null
                    isPrime: false
                    isBestSeller: false
                    isSponsored: false
                  - asin: B08HKPDZSD
                    title: Anker Ergonomic Optical USB Wired Vertical Mouse 1000/1600 DPI, 5 Buttons CE100 (Renewed)
                    url: https://www.amazon.com/dp/B08HKPDZSD
                    image: https://m.media-amazon.com/images/I/61Zu2ANcJbL._AC_UY218_.jpg
                    price: 16.89
                    currency: USD
                    priceFormatted: $16.89
                    rating: 4.5
                    reviews: null
                    isPrime: false
                    isBestSeller: false
                    isSponsored: false
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '502':
          $ref: '#/components/responses/Error502'
components:
  responses:
    Error429:
      description: Rate limit reached. Wait for Retry-After seconds. Not billed.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: rate_limit_exceeded
              message: rate limit exceeded
              retryable: true
              plan: starter
              limit_per_minute: 120
    Error422:
      description: A required parameter is missing or has the wrong type. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: Request validation failed. Fix the listed fields and retry.
              retryable: false
              issues:
              - type: missing
                loc:
                - query
                - url
                msg: Field required
                input: null
    Error404:
      description: The resource does not exist or is not public. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: NOT_FOUND
              message: Monitor not found
              retryable: false
    Error502:
      description: The platform could not be reached or returned nothing usable. Retryable, not billed. 503 and 504 use the same envelope.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: UPSTREAM_UNAVAILABLE
              message: The upstream data source failed for this request. Retry shortly.
              retryable: true
    Error401:
      description: Missing, invalid or revoked API key. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: UNAUTHORIZED
              message: Invalid or revoked API key
              retryable: false
    Error400:
      description: 'Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: WRONG_RESOURCE_TYPE
              message: Expected a TikTok URL, but received a YouTube URL. Use the YouTube endpoint for that URL, or pass a TikTok URL like https://www.tiktok.com/@user/video/1234567890.
              retryable: false
              suggestedEndpoint: /v1/youtube/video-details
    Error402:
      description: Not enough credits for this request. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: insufficient_credits
              message: This call needs 2 credits; 1 available. No credits charged.
              retryable: false
              required: 2
              available: 1
              upgrade_url: /dashboard/billing
  headers:
    ServerTiming:
      description: 'Total time the request took, in milliseconds: `total;dur=<ms>`. No per-step breakdown.'
      schema:
        type: string
      example: total;dur=4387
    Cache:
      description: 1 when the response was served from the 24h cache, 0 otherwise.
      schema:
        type: string
        enum:
        - '0'
        - '1'
    RequestId:
      description: Request id. Include it when contacting support.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    Credits:
      description: Credits charged for this request. 0 on a free cache hit or a failed request.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          const: false
        error:
          type: object
          required:
          - code
          - message
          - retryable
          properties:
            code:
              type: string
              description: Machine-readable error code, e.g. WRONG_RESOURCE_TYPE, NOT_FOUND, insufficient_credits, rate_limit_exceeded. Compare case-sensitively; both upper and lower case codes exist.
            message:
              type: string
              description: Human-readable explanation.
            retryable:
              type: boolean
              description: true when the same request may succeed later (429, most 5xx). Do not retry when false.
            suggestedEndpoint:
              type:
              - string
              - 'null'
              description: On platform mismatch, the endpoint that matches the URL you sent.
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer capt_live_...`. Create one at https://captapi.com/dashboard/api-keys.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Alternative to the bearer header: `X-API-Key: capt_live_...`.'
externalDocs:
  description: Docs
  url: https://captapi.com/docs