DocsDocsReference

Upsert collections relationships

Bulk-upserts product-to-collection relationships; sort_order is authoritative on conflict.

PUT/api/v2/{team_slug}/{app_slug}/collections/products
API
Management
Updated
Apr 26, 2026

management-api:PUT:/api/v2/{team_slug}/{app_slug}/collections/products

Bulk-upserts product-to-collection relationships; sort_order is authoritative on conflict.

API ownership

  • API family: Management API
  • Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data.
  • Do not use from: Browser-only storefront code or public clients.
  • Guide route: /apis/management/latest

The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation.

Operation

  • Method: PUT
  • Path: /api/v2/\{team_slug\}/\{app_slug\}/collections/products
  • Summary: Upsert collections relationships
  • Description: Bulk-upserts product-to-collection relationships; sort_order is authoritative on conflict.
  • OpenAPI contract: management-api
  • Operation ID: upsertProducts
Parameters2 parameters
NameInRequiredTypeDescription
Not documented in the OpenAPI contract.Not documented in the OpenAPI contract.NoanyNot documented in the OpenAPI contract.
Not documented in the OpenAPI contract.Not documented in the OpenAPI contract.NoanyNot documented in the OpenAPI contract.
Request bodyNo documented body
  • Required: Yes
  • Description: Not documented in the OpenAPI contract.
  • Content: application/json (object)

Upsert Collection Products Request

PropertyTypeRequiredDetails
productsobject[]YesminItems: 1, maxItems: 20

Upsert Collection Product Item

PropertyTypeRequiredDetails
collection_idstringYes-
product_idstringYes-
sort_orderintegerYes-

Generated example (synthetic):

{
  "products": [
    {
      "collection_id": "string",
      "product_id": "string",
      "sort_order": 0
    }
  ]
}
Responses5 statuses
StatusDescriptionContent
200OK (partial success possible)application/json (object)
400Request-level failureapplication/json (object)
401Request-level failureapplication/json (object)
403Request-level failureapplication/json (object)
500Request-level failureapplication/json (object)

200 - object

Collection Products Bulk

PropertyTypeRequiredDetails
dataobject[]Yes-
errorsobject[]Yes-
Collection Product
PropertyTypeRequiredDetails
collection_idstring (uuid)Yesformat: uuid
product_idstring (uuid)Yesformat: uuid
sort_orderintegerYes-
Collection Product Error
PropertyTypeRequiredDetails
collection_idstring (uuid)Yesformat: uuid
product_idstring (uuid)Yesformat: uuid
messagestringYes-

Generated example (synthetic):

{
  "data": [
    {
      "collection_id": "00000000-0000-0000-0000-000000000000",
      "product_id": "00000000-0000-0000-0000-000000000000",
      "sort_order": 0
    }
  ],
  "errors": [
    {
      "collection_id": "00000000-0000-0000-0000-000000000000",
      "product_id": "00000000-0000-0000-0000-000000000000",
      "message": "string"
    }
  ]
}

400 - object

Error

PropertyTypeRequiredDetails
errorobjectYes-
Error Body
PropertyTypeRequiredDetails
messagestringYes-
detailsstring[]Yes-

Generated example (synthetic):

{
  "error": {
    "message": "string",
    "details": [
      "string"
    ]
  }
}

401 - object

Error

PropertyTypeRequiredDetails
errorobjectYes-
Error Body
PropertyTypeRequiredDetails
messagestringYes-
detailsstring[]Yes-

Generated example (synthetic):

{
  "error": {
    "message": "string",
    "details": [
      "string"
    ]
  }
}

403 - object

Error

PropertyTypeRequiredDetails
errorobjectYes-
Error Body
PropertyTypeRequiredDetails
messagestringYes-
detailsstring[]Yes-

Generated example (synthetic):

{
  "error": {
    "message": "string",
    "details": [
      "string"
    ]
  }
}

500 - object

Error

PropertyTypeRequiredDetails
errorobjectYes-
Error Body
PropertyTypeRequiredDetails
messagestringYes-
detailsstring[]Yes-

Generated example (synthetic):

{
  "error": {
    "message": "string",
    "details": [
      "string"
    ]
  }
}

Contract identity

Use these fields to confirm you are implementing the intended endpoint contract.

  • API family: Management API
  • Method: PUT
  • Path: /api/v2/\{team_slug\}/\{app_slug\}/collections/products
  • Operation ID: upsertProducts
  • OpenAPI tag: Collections V2
  • OpenAPI summary: Upsert collections relationships

Upsert collections relationships

# Upsert collections relationships Bulk-upserts product-to-collection relationships; sort_order is authoritative on conflict.
PUT /api/v2/{team_slug}/{app_slug}/collections/products
Purpose

Bulk-upserts product-to-collection relationships; sort_order is authoritative on conflict.

Required inputs

None documented

Primary response

200 ยท OK (partial success possible)

Operation key

management-api:PUT:/api/v2/{team_slug}/{app_slug}/collections/products

## API ownership - API family: Management API - Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data. - Do not use from: Browser-only storefront code or public clients. - Guide route: [/apis/management/latest](/apis/management/latest) The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation. ## Operation - Method: `PUT` - Path: `/api/v2/{team_slug}/{app_slug}/collections/products` - Summary: Upsert collections relationships - Description: Bulk-upserts product-to-collection relationships; sort_order is authoritative on conflict. - OpenAPI contract: management-api - Operation ID: upsertProducts - Stable operation key: `management-api:PUT:/api/v2/{team_slug}/{app_slug}/collections/products` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | Not documented in the OpenAPI contract. | Not documented in the OpenAPI contract. | No | any | Not documented in the OpenAPI contract. | | Not documented in the OpenAPI contract. | Not documented in the OpenAPI contract. | No | any | Not documented in the OpenAPI contract. | ## Request body - Required: Yes - Description: Not documented in the OpenAPI contract. - Content: application/json (object) ### Upsert Collection Products Request | Property | Type | Required | Details | | --- | --- | --- | --- | | `products` | object[] | Yes | minItems: 1, maxItems: 20 | #### Upsert Collection Product Item | Property | Type | Required | Details | | --- | --- | --- | --- | | `collection_id` | string | Yes | - | | `product_id` | string | Yes | - | | `sort_order` | integer | Yes | - | **Generated example (synthetic):** ```json { "products": [ { "collection_id": "string", "product_id": "string", "sort_order": 0 } ] } ``` ## Responses | Status | Description | Content | | --- | --- | --- | | 200 | OK (partial success possible) | application/json (object) | | 400 | Request-level failure | application/json (object) | | 401 | Request-level failure | application/json (object) | | 403 | Request-level failure | application/json (object) | | 500 | Request-level failure | application/json (object) | ### 200 - object #### Collection Products Bulk | Property | Type | Required | Details | | --- | --- | --- | --- | | `data` | object[] | Yes | - | | `errors` | object[] | Yes | - | ##### Collection Product | Property | Type | Required | Details | | --- | --- | --- | --- | | `collection_id` | string (uuid) | Yes | format: uuid | | `product_id` | string (uuid) | Yes | format: uuid | | `sort_order` | integer | Yes | - | ##### Collection Product Error | Property | Type | Required | Details | | --- | --- | --- | --- | | `collection_id` | string (uuid) | Yes | format: uuid | | `product_id` | string (uuid) | Yes | format: uuid | | `message` | string | Yes | - | **Generated example (synthetic):** ```json { "data": [ { "collection_id": "00000000-0000-0000-0000-000000000000", "product_id": "00000000-0000-0000-0000-000000000000", "sort_order": 0 } ], "errors": [ { "collection_id": "00000000-0000-0000-0000-000000000000", "product_id": "00000000-0000-0000-0000-000000000000", "message": "string" } ] } ``` ### 400 - object #### Error | Property | Type | Required | Details | | --- | --- | --- | --- | | `error` | object | Yes | - | ##### Error Body | Property | Type | Required | Details | | --- | --- | --- | --- | | `message` | string | Yes | - | | `details` | string[] | Yes | - | **Generated example (synthetic):** ```json { "error": { "message": "string", "details": [ "string" ] } } ``` ### 401 - object #### Error | Property | Type | Required | Details | | --- | --- | --- | --- | | `error` | object | Yes | - | ##### Error Body | Property | Type | Required | Details | | --- | --- | --- | --- | | `message` | string | Yes | - | | `details` | string[] | Yes | - | **Generated example (synthetic):** ```json { "error": { "message": "string", "details": [ "string" ] } } ``` ### 403 - object #### Error | Property | Type | Required | Details | | --- | --- | --- | --- | | `error` | object | Yes | - | ##### Error Body | Property | Type | Required | Details | | --- | --- | --- | --- | | `message` | string | Yes | - | | `details` | string[] | Yes | - | **Generated example (synthetic):** ```json { "error": { "message": "string", "details": [ "string" ] } } ``` ### 500 - object #### Error | Property | Type | Required | Details | | --- | --- | --- | --- | | `error` | object | Yes | - | ##### Error Body | Property | Type | Required | Details | | --- | --- | --- | --- | | `message` | string | Yes | - | | `details` | string[] | Yes | - | **Generated example (synthetic):** ```json { "error": { "message": "string", "details": [ "string" ] } } ``` ## Contract identity Use these fields to confirm you are implementing the intended endpoint contract. - API family: Management API - Method: `PUT` - Path: `/api/v2/{team_slug}/{app_slug}/collections/products` - Operation ID: upsertProducts - Stable operation key: `management-api:PUT:/api/v2/{team_slug}/{app_slug}/collections/products` - OpenAPI tag: Collections V2 - OpenAPI summary: Upsert collections relationships