Skip to content

[D2] Document the ecommerce product events endpoint (Preview) #719

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rkaahean merged 1 commit into from
Oct 14, 2026
Merged

[D2] Document the ecommerce product events endpoint (Preview) #719

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
312 changes: 312 additions & 0 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20502,6 +20502,236 @@ paths:
message: Failed to store catalog
schema:
"$ref": "#/components/schemas/error"
"/ecommerce/connectors/{id}/events":
post:
summary: Submit a product event
parameters:
- name: Intercom-Version
in: header
schema:
"$ref": "#/components/schemas/intercom_version_preview"
- name: id
in: path
required: true
description: The unique identifier of the ecommerce connector.
schema:
type: string
example: '42939'
tags:
- Ecommerce Connectors
operationId: submitEcommerceProductEvent
description: |
Send a single product change to an ecommerce connector. Use product events to keep
Fin's product knowledge current between full catalog uploads. Each request carries
one event.

A full catalog must be uploaded with
[Upload a product catalog](/docs/references/preview/rest-api/api.intercom.io/ecommerce-connectors/uploadecommercecatalog)
before you send events. Until then, this endpoint returns `409 Conflict`.

## Event types

| `type` | `data` | Effect |
|---|---|---|
| `product.created` | `product` | Adds the product, or updates it if a product with the same `id` already exists. |
| `product.updated` | `product` | Updates the product with the same `id`, or adds it if it does not exist yet. |
| `product.deleted` | `product_id` | Removes the product from Fin's knowledge. |

For `product.created` and `product.updated`, send the full product object, not only the
fields that changed. It uses the same fields as a catalog product
([`ecommerce_catalog_product`](/docs/references/preview/rest-api/api.intercom.io/models/ecommerce_catalog_product)),
plus a required `updated_at` timestamp. The product is matched by `id`. The serialized
product must be 60 KB or smaller.

For `product.deleted`, send only `data.product_id`.

`occurred_at` is required on every event and must be an ISO 8601 timestamp.

## Ordering

Events can arrive out of order. The newest version of a product wins:

- If the stored product has a newer `updated_at` than the product in a
`product.created` or `product.updated` event, the event is ignored.
- If the stored product has a newer `updated_at` than a `product.deleted` event's
`occurred_at`, the delete is ignored.
- Once a product is deleted, an update with an older `updated_at` than the delete's
`occurred_at` does not bring it back.
- Events sent while a full catalog upload is running are kept.

## Processing

The endpoint returns `202 Accepted` with an `event_id` once the event is queued.
Processing is asynchronous, so the change may take a short time to reach Fin.
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ecommerce_product_event_request"
examples:
product_created:
summary: Product created
value:
type: product.created
occurred_at: '2026-10-14T09:30:00Z'
data:
product:
id: 'tent-2p-ultralight'
title: 'Ridgeline 2-Person Ultralight Tent'
url: 'https://example.com/products/ridgeline-2p-tent'
description: 'A freestanding two-person backpacking tent that weighs under 1.5 kg.'
featured_image_url: 'https://cdn.example.com/images/ridgeline-2p.jpg'
price_min: 349.0
price_max: 379.0
currency: 'USD'
in_stock: true
category_path:
- 'Camping'
- 'Tents'
collections:
- 'Backpacking'
tags:
- 'ultralight'
- 'freestanding'
available_options:
- name: 'Color'
values:
- 'Green'
- 'Orange'
variants:
- id: 'tent-2p-ultralight-green'
title: 'Green'
price: 349.0
in_stock: true
selected_options:
- name: 'Color'
value: 'Green'
- id: 'tent-2p-ultralight-orange'
title: 'Orange'
price: 379.0
in_stock: true
selected_options:
- name: 'Color'
value: 'Orange'
created_at: '2026-10-14T09:30:00Z'
updated_at: '2026-10-14T09:30:00Z'
product_updated:
summary: Product updated
value:
type: product.updated
occurred_at: '2026-10-15T14:05:00Z'
data:
product:
id: 'tent-2p-ultralight'
title: 'Ridgeline 2-Person Ultralight Tent'
url: 'https://example.com/products/ridgeline-2p-tent'
description: 'A freestanding two-person backpacking tent that weighs under 1.5 kg.'
featured_image_url: 'https://cdn.example.com/images/ridgeline-2p.jpg'
price_min: 299.0
price_max: 379.0
currency: 'USD'
in_stock: true
category_path:
- 'Camping'
- 'Tents'
collections:
- 'Backpacking'
- 'Sale'
tags:
- 'ultralight'
- 'freestanding'
available_options:
- name: 'Color'
values:
- 'Green'
- 'Orange'
variants:
- id: 'tent-2p-ultralight-green'
title: 'Green'
price: 299.0
compare_at_price: 349.0
in_stock: true
selected_options:
- name: 'Color'
value: 'Green'
- id: 'tent-2p-ultralight-orange'
title: 'Orange'
price: 379.0
in_stock: false
selected_options:
- name: 'Color'
value: 'Orange'
created_at: '2026-10-14T09:30:00Z'
updated_at: '2026-10-15T14:05:00Z'
product_deleted:
summary: Product deleted
value:
type: product.deleted
occurred_at: '2026-10-20T08:00:00Z'
data:
product_id: 'tent-2p-ultralight'
responses:
'202':
description: Event accepted and queued for processing.
content:
application/json:
examples:
Event accepted:
value:
event_id: 81273
schema:
"$ref": "#/components/schemas/ecommerce_product_event_response"
'400':
description: The event is invalid. All validation errors are returned in `message`, separated by `; `.
content:
application/json:
examples:
Invalid type:
value:
type: invalid_event
message: type must be one of product.created, product.updated, product.deleted
Invalid product:
value:
type: invalid_event
message: data.product.title is required; data.product.updated_at must be an ISO 8601 timestamp
Missing product id on delete:
value:
type: invalid_event
message: data.product_id is required
Product too large:
value:
type: invalid_event
message: data.product exceeds 60KB
schema:
"$ref": "#/components/schemas/ecommerce_product_event_error"
'401':
"$ref": "#/components/responses/Unauthorized"
'404':
description: Not found.
content:
application/json:
examples:
Connector not found:
value:
type: import_source_not_found
message: No connector found with the provided import_source_id.
Feature not available:
value:
type: not_found
message: The events API is not available for this workspace.
schema:
"$ref": "#/components/schemas/ecommerce_product_event_error"
'409':
description: No full catalog has been uploaded to this connector yet.
content:
application/json:
examples:
Catalog not uploaded:
value:
type: catalog_not_uploaded
message: Upload a full catalog before sending product events.
schema:
"$ref": "#/components/schemas/ecommerce_product_event_error"
"/events":
post:
summary: Submit a data event
Expand Down Expand Up @@ -40066,6 +40296,88 @@ components:
sku: 'TSHIRT-BLU-L'
vendor: 'Acme Apparel'
nullable: true
ecommerce_product_event_error:
title: Ecommerce Product Event Error
type: object
description: Returned when a product event is rejected.
properties:
type:
type: string
description: The error code.
enum:
- invalid_event
- import_source_not_found
- not_found
- catalog_not_uploaded
example: invalid_event
message:
type: string
description: A human-readable description of the error. For `invalid_event`, every validation error is listed, separated by `; `.
example: data.product.id is required
ecommerce_product_event_product:
title: Ecommerce Product Event Product
description: |
The full product sent in a `product.created` or `product.updated` event. It uses the same
fields as `ecommerce_catalog_product`, plus `updated_at`, which is required. The serialized
product must be 60 KB or smaller.
allOf:
- "$ref": "#/components/schemas/ecommerce_catalog_product"
- type: object
required:
- updated_at
properties:
created_at:
type: string
format: date-time
description: When the product was created in your store, as an ISO 8601 timestamp.
example: '2026-10-14T09:30:00Z'
nullable: true
updated_at:
type: string
format: date-time
description: When the product was last changed in your store, as an ISO 8601 timestamp. Used to order events, so an older version never overwrites a newer one.
example: '2026-10-15T14:05:00Z'
ecommerce_product_event_request:
title: Ecommerce Product Event Request
type: object
description: A single product event.
required:
- type
- occurred_at
- data
properties:
type:
type: string
description: The kind of product change.
enum:
- product.created
- product.updated
- product.deleted
example: product.updated
occurred_at:
type: string
format: date-time
description: When the change happened, as an ISO 8601 timestamp. For `product.deleted`, this is compared with the stored product's `updated_at` to decide whether the delete applies.
example: '2026-10-15T14:05:00Z'
data:
type: object
description: The event payload. Send `product` for `product.created` and `product.updated`, and `product_id` for `product.deleted`.
properties:
product:
"$ref": "#/components/schemas/ecommerce_product_event_product"
product_id:
type: string
description: The `id` of the product to delete. Required for `product.deleted`.
example: 'tent-2p-ultralight'
ecommerce_product_event_response:
title: Ecommerce Product Event Response
type: object
description: Returned when a product event is accepted and queued.
properties:
event_id:
type: integer
description: The unique identifier for the queued event.
example: 81273
email_address_header:
title: Email Address Header
type: object
Expand Down
Loading