Get All Products

GET https://api.firmly.work/api/v1/domains-products/{merchant-domain}

Retrieves a paginated list of all products from a merchant’s store. This endpoint returns product summaries with links to retrieve full details for each product.

​​ Authentication

• x-firmly-authorization (string, required) — Device access token from Browser Session

​​ Path Parameters

• merchant-domain (string, required) — The domain of the merchant website (e.g., staging.luma.gift)

​​ Query Parameters

• page (number, default 1) — Page number for pagination

• size (number, default 2000) — Number of products per page. Valid values: 100, 500, 1000, 2000

• countryCode (string, default us) — Country code for regional product availability. Case-insensitive — us and US are treated the same; the value is normalized and echoed back in metadata.countryCode (e.g. US).

​​ Response

Returns an object with metadata describing the page and a products array.

• metadata (object) — Page and source metadata.

  Metadata

  • page (integer) — Current page number (1-indexed)
  • size (integer) — Requested page size — echoes the size query parameter (one of 100, 500, 1000, 2000), not the count of products returned. On the final page the products array may be shorter than size.
  • totalRecords (integer) — Total products in the merchant catalog
  • totalPages (integer) — Total pages available at the current size
  • domain (string) — Merchant domain this catalog belongs to
  • countryCode (string) — ISO country code applied to this query
  • startIndex (integer) — Zero-indexed position of the first product on this page
  • endIndex (integer) — Zero-indexed position of the last product on this page
  • generatedAt (string) — ISO 8601 timestamp when the catalog snapshot was generated
  • lastPullAt (string) — ISO 8601 timestamp of the last upstream sync from the merchant
  • version (string) — Snapshot version identifier
  • source (string) — Source pipeline that generated the catalog (typically get-all-products-workflow)

• products (array) — Array of product summaries.

  Product Summary

  • handle (string) — Product handle/identifier
  • title (string) — Product title
  • pdp_url (string) — Full URL to the product detail page on the merchant’s site
  • loc (string) — Full URL to retrieve detailed product information via the Get Product from URL endpoint
  • image (object) — Primary product image — { "url": "..." }

​​ Request Example

curl --request GET \
  --url 'https://api.firmly.work/api/v1/domains-products/staging.luma.gift?page=1&size=100' \
  --header 'x-firmly-authorization: YOUR_AUTH_TOKEN'

​​ Response Example

{
  "metadata": {
    "page": 1,
    "size": 100,
    "totalRecords": 132,
    "totalPages": 2,
    "domain": "staging.luma.gift",
    "countryCode": "US",
    "startIndex": 0,
    "endIndex": 99,
    "generatedAt": "2026-02-16T10:46:30.569Z",
    "lastPullAt": "2026-02-16T10:46:30.569Z",
    "version": "20260216T104629Z",
    "source": "generate-all-products"
  },
  "products": [
    {
      "handle": "radiant-tee",
      "title": "Radiant Tee",
      "pdp_url": "https://staging.luma.gift/radiant-tee.html",
      "loc": "https://api.firmly.work/api/v1/domains-pdp?url=https%3A%2F%2Fstaging.luma.gift%2Fradiant-tee.html",
      "image": {
        "url": "https://cdn.staging.luma.gift/products/radiant-tee-main.jpg"
      }
    },
    {
      "handle": "hero-hoodie",
      "title": "Hero Hoodie",
      "pdp_url": "https://staging.luma.gift/hero-hoodie.html",
      "loc": "https://api.firmly.work/api/v1/domains-pdp?url=https%3A%2F%2Fstaging.luma.gift%2Fhero-hoodie.html",
      "image": {
        "url": "https://cdn.staging.luma.gift/products/hero-hoodie-main.jpg"
      }
    }
  ]
}

​​ Error Responses

Errors return a JSON body with code, error, and description. Program against the error value — descriptions are human-readable and may change.

{ "error": "Size is not valid: valid values are 100, 500, 1000, 2000" }

{ "code": 400, "error": "MissingAuthHeader", "description": "x-firmly-authorization header is missing or invalid." }

{ "code": 400, "error": "InvalidToken", "description": "Jwt token is invalid." }

{ "code": 401, "error": "InvalidJWTToken", "description": "Jwt token is invalid." }

{ "code": 404, "error": "PartnerNotFound", "description": "Partner not found." }

{ "code": 404, "error": "DomainNotFound", "description": "This domain was not found in firmly servers." }

{ "code": 404, "error": "AllProductsNotFound", "description": "All products not found." }

{ "code": 412, "error": "OperationNotSupported", "description": "This operation is not supported for this store." }