From 836d633c1cfc0019a6581cb38ddb790d020a09df Mon Sep 17 00:00:00 2001 From: harish-intercom Date: Thu, 9 Jul 2026 14:08:26 +0100 Subject: [PATCH 1/3] Add code sample examples to ecommerce catalog upload API spec Adds labeled cURL examples for single-file upload and all three multipart steps (first part, append part, finalize). Co-Authored-By: Claude Sonnet 4.6 --- descriptions/0/api.intercom.io.yaml | 47 +++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 451ad49..9353eae 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -16390,6 +16390,53 @@ paths: Part uploads are idempotent — retrying the same `part_number` does not create a duplicate. If a response is lost, retry with the same `part_number`. + x-code-samples: + - lang: 'cURL' + label: 'Single-file upload' + source: | + curl -X POST "https://api.intercom.io/ecommerce/connectors/44734/catalog" \ + -H "Authorization: Bearer {access_token}" \ + -H "Accept: application/json" \ + -H "Intercom-Version: Preview" \ + -F "catalog=@products.json;type=application/json" + - lang: 'cURL' + label: 'Multipart — Step 1: First part' + source: | + curl -X POST "https://api.intercom.io/ecommerce/connectors/44734/catalog" \ + -H "Authorization: Bearer {access_token}" \ + -H "Accept: application/json" \ + -H "Intercom-Version: Preview" \ + -F "catalog=@products_part1.json;type=application/json" \ + -F "finalize=false" + + # Response: {"import_job_id": "job_01abc123", "next_part_number": 2} + - lang: 'cURL' + label: 'Multipart — Step 2: Append part' + source: | + # Use the import_job_id from Step 1 and the next_part_number from the previous response + curl -X POST "https://api.intercom.io/ecommerce/connectors/44734/catalog" \ + -H "Authorization: Bearer {access_token}" \ + -H "Accept: application/json" \ + -H "Intercom-Version: Preview" \ + -F "catalog=@products_part2.json;type=application/json" \ + -F "finalize=false" \ + -F "import_job_id=job_01abc123" \ + -F "part_number=2" + + # Response: {"import_job_id": "job_01abc123", "next_part_number": 3} + # Repeat this step for each subsequent part, incrementing part_number accordingly + - lang: 'cURL' + label: 'Multipart — Step 3: Finalize' + source: | + # No catalog file required — this triggers the sync + curl -X POST "https://api.intercom.io/ecommerce/connectors/44734/catalog" \ + -H "Authorization: Bearer {access_token}" \ + -H "Accept: application/json" \ + -H "Intercom-Version: Preview" \ + -F "finalize=true" \ + -F "import_job_id=job_01abc123" + + # Response: {"import_job_id": "job_01abc123", "status": "processing", "message": "Catalog received. Sync has started."} requestBody: content: multipart/form-data: From d2a77033207619d2c082dca302895e85a50c253c Mon Sep 17 00:00:00 2001 From: harish-intercom Date: Thu, 9 Jul 2026 14:26:00 +0100 Subject: [PATCH 2/3] Replace x-code-samples with standard OpenAPI examples for catalog upload --- descriptions/0/api.intercom.io.yaml | 69 +++++++++-------------------- 1 file changed, 22 insertions(+), 47 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 9353eae..de1046a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -16390,53 +16390,6 @@ paths: Part uploads are idempotent — retrying the same `part_number` does not create a duplicate. If a response is lost, retry with the same `part_number`. - x-code-samples: - - lang: 'cURL' - label: 'Single-file upload' - source: | - curl -X POST "https://api.intercom.io/ecommerce/connectors/44734/catalog" \ - -H "Authorization: Bearer {access_token}" \ - -H "Accept: application/json" \ - -H "Intercom-Version: Preview" \ - -F "catalog=@products.json;type=application/json" - - lang: 'cURL' - label: 'Multipart — Step 1: First part' - source: | - curl -X POST "https://api.intercom.io/ecommerce/connectors/44734/catalog" \ - -H "Authorization: Bearer {access_token}" \ - -H "Accept: application/json" \ - -H "Intercom-Version: Preview" \ - -F "catalog=@products_part1.json;type=application/json" \ - -F "finalize=false" - - # Response: {"import_job_id": "job_01abc123", "next_part_number": 2} - - lang: 'cURL' - label: 'Multipart — Step 2: Append part' - source: | - # Use the import_job_id from Step 1 and the next_part_number from the previous response - curl -X POST "https://api.intercom.io/ecommerce/connectors/44734/catalog" \ - -H "Authorization: Bearer {access_token}" \ - -H "Accept: application/json" \ - -H "Intercom-Version: Preview" \ - -F "catalog=@products_part2.json;type=application/json" \ - -F "finalize=false" \ - -F "import_job_id=job_01abc123" \ - -F "part_number=2" - - # Response: {"import_job_id": "job_01abc123", "next_part_number": 3} - # Repeat this step for each subsequent part, incrementing part_number accordingly - - lang: 'cURL' - label: 'Multipart — Step 3: Finalize' - source: | - # No catalog file required — this triggers the sync - curl -X POST "https://api.intercom.io/ecommerce/connectors/44734/catalog" \ - -H "Authorization: Bearer {access_token}" \ - -H "Accept: application/json" \ - -H "Intercom-Version: Preview" \ - -F "finalize=true" \ - -F "import_job_id=job_01abc123" - - # Response: {"import_job_id": "job_01abc123", "status": "processing", "message": "Catalog received. Sync has started."} requestBody: content: multipart/form-data: @@ -16449,6 +16402,28 @@ paths: description: | The catalog JSON file. Required for all requests except finalization (`finalize=true`). Must be a valid JSON array of objects. Max 99 MB. + examples: + single_file_upload: + summary: Single-file upload + value: + catalog: "@products.json" + multipart_first_part: + summary: "Multipart — Step 1: First part" + value: + catalog: "@products_part1.json" + finalize: "false" + multipart_append_part: + summary: "Multipart — Step 2: Append part" + value: + catalog: "@products_part2.json" + finalize: "false" + import_job_id: "job_01abc123" + part_number: 2 + multipart_finalize: + summary: "Multipart — Step 3: Finalize" + value: + finalize: "true" + import_job_id: "job_01abc123" responses: '200': description: Multipart catalog part uploaded successfully. From 55aaac2a984b26438696681d83f69ba782d5673c Mon Sep 17 00:00:00 2001 From: harish-intercom Date: Thu, 9 Jul 2026 14:43:34 +0100 Subject: [PATCH 3/3] Fix finalize/import_job_id/part_number as form fields not query params Co-Authored-By: Claude Sonnet 4.6 --- descriptions/0/api.intercom.io.yaml | 57 ++++++++++++----------------- 1 file changed, 24 insertions(+), 33 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index de1046a..73eb3f9 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -16336,39 +16336,6 @@ paths: schema: type: string example: '42939' - - name: import_job_id - in: query - required: false - description: | - The import job ID returned from the first multipart upload request. Required - when uploading subsequent parts (`part_number` ≥ 2) and when finalizing - a multipart session (`finalize=true`). - schema: - type: string - example: 'job_01abc123' - - name: part_number - in: query - required: false - description: | - The sequential part number for a multipart upload. Must be a positive integer. - The server returns `next_part_number` in each response to guide the next request. - Retrying the same `part_number` is safe and idempotent. - schema: - type: integer - example: 2 - - name: finalize - in: query - required: false - description: | - Set to `true` to finalize a multipart upload session and start the catalog sync. - No catalog file is required when finalizing. Set to `false` to upload a part in - a multipart session. Omit entirely for a single-file upload. - schema: - type: string - enum: - - 'true' - - 'false' - example: 'false' tags: - Ecommerce Connectors operationId: uploadEcommerceCatalog @@ -16402,6 +16369,30 @@ paths: description: | The catalog JSON file. Required for all requests except finalization (`finalize=true`). Must be a valid JSON array of objects. Max 99 MB. + finalize: + type: string + enum: + - 'true' + - 'false' + description: | + Set to `true` to finalize a multipart upload session and start the catalog sync. + No catalog file is required when finalizing. Set to `false` to upload a part in + a multipart session. Omit entirely for a single-file upload. + example: 'false' + import_job_id: + type: string + description: | + The import job ID returned from the first multipart upload request. Required + when uploading subsequent parts (`part_number` ≥ 2) and when finalizing + a multipart session (`finalize=true`). + example: 'job_01abc123' + part_number: + type: integer + description: | + The sequential part number for a multipart upload. Must be a positive integer. + The server returns `next_part_number` in each response to guide the next request. + Retrying the same `part_number` is safe and idempotent. + example: 2 examples: single_file_upload: summary: Single-file upload