PRprivy
Products

List products

Changed on

Retrieve the product catalog of your connected store (Shopify or BigCommerce), proxied live from the store's API.

Unlike the other list endpoints, products use cursor pagination: pass the next_cursor from each response as ?cursor= to fetch the next page, keeping the same filters. There are no page numbers.

Requires a connected Shopify or BigCommerce store — without one, this endpoint returns 404 no_connected_store.

The response shape is the same on both platforms; fields BigCommerce does not supply (product_type, vendor, url) are null. Large per_page values can be slow on BigCommerce stores whose products carry many variants — reduce per_page if requests return 502 store_unavailable.

A live read of the store's own catalog — nothing here is Privy data, and no endpoint reports sales or performance per product. /v1/products/{id} adds description, tags, options, and images.

Required scope: products_read

get/products

Request

  • Base URL
    https://api.privy.com/v1
  • Auth
    HTTP bearer

Query parameters

per_pageinteger

Number of results per page. Products default lower than other endpoints and clamp to 1–50 — these reads proxy the store live, and large pages on variant-heavy BigCommerce catalogs get expensive.

titlestring

Narrow to products whose title matches, at most 255 characters. Matching differs by platform. On Shopify stores, each word of the value must start a word of the title: a word is a run of letters and digits, apostrophes inside it included (O'Neill), and at least one is required. On BigCommerce stores, the title must contain the value as typed, where % and _ may act as wildcards.

handlestring

Narrow to the product with this exact handle (the slug in its storefront URL). Letters, digits, hyphens and underscores only. A Shopify-only filter: BigCommerce stores have no product handle and return 422 validation_failed.

cursorstring

Opaque pagination cursor from a previous response's pagination.next_cursor.

Headers

Privy-Account-Idstring

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

Response

A page of the store's product catalog.

Example response

{
  "data": [
    {
      "id": 7890123456789,
      "title": "Classic T-Shirt",
      "handle": "classic-t-shirt",
      "status": "active",
      "product_type": "Shirts",
      "vendor": "Acme Apparel",
      "url": "https://mystore.com/products/classic-t-shirt",
      "image_url": "https://cdn.shopify.com/s/files/1/0001/products/tshirt.jpg",
      "price_range": {
        "min": "10.00",
        "max": "15.00",
        "currency_code": "USD"
      },
      "total_inventory": 42,
      "tracks_inventory": true,
      "variants_count": 3,
      "variants": [
        {
          "id": 40012345678901,
          "title": "Small",
          "price": "10.00",
          "compare_at_price": "15.00",
          "sku": "TSHIRT-S",
          "inventory_quantity": 12,
          "available": true
        }
      ],
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-06-01T09:00:00Z"
    }
  ],
  "pagination": {
    "per_page": 40,
    "total_count": 128,
    "has_more": true,
    "next_cursor": "eyJsYXN0X2lkIjo3ODkwMTIzNDU2Nzg5fQ=="
  }
}

Changes

  • cf0885e90d5aRevision changes
    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

  • fe500ab59b3bRevision changes
    • info

      endpoint added