# Catalog and commerce

## Endpoints

- `GET /graph/whatsapp/{version}/{wabaId}/product_catalogs`: [List linked product catalogs](https://docs.polymorfa.com/api/graph/catalog-and-commerce/list-linked-product-catalogs)
- `GET /graph/whatsapp/{version}/{wabaId}/product_catalogs/{catalogId}/products`: [List linked catalog products](https://docs.polymorfa.com/api/graph/catalog-and-commerce/list-linked-catalog-products)
- `GET /graph/whatsapp/{version}/{phoneNumberId}/whatsapp_commerce_settings`: [Get commerce settings](https://docs.polymorfa.com/api/graph/catalog-and-commerce/get-commerce-settings)
- `POST /graph/whatsapp/{version}/{phoneNumberId}/whatsapp_commerce_settings`: [Update commerce settings](https://docs.polymorfa.com/api/graph/catalog-and-commerce/update-commerce-settings)

## List linked product catalogs

`GET https://api.polymorfa.com/graph/whatsapp/{version}/{wabaId}/product_catalogs` (Graph API)

Required permission: `sessions:read`

**Protocols:** Meta Cloud API

**Required scope:** `sessions:read`

Reads Meta's product_catalogs edge for a WhatsApp Business Account that has an Official API Number in the authenticated project. Meta determines catalog visibility and returns permission errors when the connected credentials lack access.

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `wabaId` (string, required). Identifier for the waba.

### Query parameters

- `limit` (integer, range 1–100). Specifies limit for this query parameter.
- `after` (string, length 1–4096). Specifies after for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<wabaId>/product_catalogs" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Linked product catalogs, with Meta pagination when present
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `name` (string). Human-readable name for this resource.
- `paging` (object). Structured paging values for this graph graph product catalogs response.
  - `cursors` (object, required). Structured cursors values for this paging.
    - `before` (string). Specifies before for this cursor.
    - `after` (string). Specifies after for this cursor.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "data": [
    {
      "id": "string"
    }
  ]
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## List linked catalog products

`GET https://api.polymorfa.com/graph/whatsapp/{version}/{wabaId}/product_catalogs/{catalogId}/products` (Graph API)

Required permission: `sessions:read`

**Protocols:** Meta Cloud API

**Required scope:** `sessions:read`

Reads a small product projection from a catalog linked to an Official API Number's WABA in the authenticated project. Meta controls product visibility and permissions. This is a Polymorfa WABA-scoped path; Meta's product edge is `/{catalogId}/products`.

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `wabaId` (string, required). Identifier for the waba.
- `catalogId` (string, required, pattern ^[0-9]+$). Identifier of the WhatsApp catalog.

### Query parameters

- `limit` (integer, range 1–100). Specifies limit for this query parameter.
- `after` (string, length 1–4096). Specifies after for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<wabaId>/product_catalogs/<catalogId>/products" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Linked catalog products and Meta cursors
- `data` (array of object, required, max items 1000). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `retailer_id` (string). Identifier for the retailer.
  - `name` (string). Human-readable name for this resource.
  - `availability` (string). Specifies availability for this data.
- `paging` (object). Structured paging values for this graph graph catalog products response.
  - `cursors` (object, required). Structured cursors values for this paging.
    - `after` (string). Specifies after for this cursor.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "data": [
    {
      "id": "string"
    }
  ]
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Get commerce settings

`GET https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/whatsapp_commerce_settings` (Graph API)

Required permission: `sessions:read`

**Protocols:** Meta Cloud API

**Required scope:** `sessions:read`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Request

```bash
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/whatsapp_commerce_settings" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Commerce settings

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Update commerce settings

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/whatsapp_commerce_settings` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body


### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/whatsapp_commerce_settings" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d 'null'
```

### Responses

#### 200

Updated commerce settings

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```
