Skip to main content
  • Send to AI

Bulk Share Collections

Share every owned content item that belongs to one or more collections with a list of target tenants in a single API call. The endpoint validates the request synchronously and queues the sharing work in the background.

For per-item sharing using the share_with_tenants_ids field, see Content Sharing.

Endpoint​

POST /api/v3/content/share

Headers​

HeaderRequiredDescription
X-User-TokenYesAPI token of the content owner
Content-TypeYesMust be application/json
AcceptNoapplication/json (recommended)

All requests must use HTTPS.

Request Body​

{
  "collections": ["Fall Releases 2026", "nonfiction-bestsellers"],
  "tenant_ids": [42, 87, 153]
}

Fields​

FieldTypeRequiredDescription
collectionsarray of stringsYesCollections owned by your tenant. Each value can be the collection name shown in your dashboard or its slug (1 to 50, max 200 chars per value)
tenant_idsarray of integersOne of these is requiredInternal IDs of the target tenants (1 to 50)
tenant_external_idsarray of stringsOne of these is requiredExternal IDs of the target tenants (1 to 50, max 255 chars)
Names or Slugs

Each value in collections is matched against both the collection's display name (for example, Fall Releases 2026) and its stored slug (for example, fall-releases-2026). You can mix both forms in the same request. Names are matched literally as stored, including spaces, casing, and accents.

Mutually Exclusive

Send either tenant_ids or tenant_external_ids, never both. Including both fields returns a 422 validation error.

Limits​

LimitValue
Maximum collections per request50
Maximum target tenants per request50

The endpoint shares the bulk rate limit bucket with Bulk Operations: 10 requests per minute per API token.

How It Works​

  1. The endpoint validates the request: every value in collections must match a collection (by name or slug) that exists and belongs to your tenant, and every target tenant must be authorized to receive shared content.
  2. The endpoint queues one background job per target tenant. Each job iterates through the matching content items in chunks and inserts the corresponding catalog entries on the target tenant.
  3. The endpoint returns 202 Accepted immediately. Sharing completes asynchronously; the receiving tenant's catalog updates as the jobs run.
  4. The endpoint is idempotent: items already shared are skipped, so re-running the same request does not create duplicates.
Owned content only

Only content owned by your tenant is shared. Items that you received as shared from a third-party owner, or that came from the marketplace as retail, are skipped without being reported in the response.

Authorized Targets​

A target tenant is accepted in two cases:

CaseDescription
Aggregated tenantsTenants that list your tenant as their aggregator
Explicit share permissionTenants for which you have been granted the content_share permission (configured by support)

Tenants that fall outside both cases are rejected with 422, and the response lists the unauthorized IDs. Validation is all-or-nothing: if any target is unauthorized, no jobs are queued.

Request Examples​

Share One Collection With One Tenant (Using the Display Name)​

curl -X POST "https://yourstore.publica.la/api/v3/content/share" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": ["Fall Releases 2026"],
    "tenant_ids": [42]
  }'

Share Multiple Collections With Multiple Tenants (Mixing Names and Slugs)​

curl -X POST "https://yourstore.publica.la/api/v3/content/share" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": ["Fall Releases 2026", "nonfiction-bestsellers"],
    "tenant_ids": [42, 87, 153]
  }'

Use External Tenant IDs​

curl -X POST "https://yourstore.publica.la/api/v3/content/share" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": ["Fall Releases 2026"],
    "tenant_external_ids": ["partner-store-eu", "partner-store-us"]
  }'

Response​

Success (202 Accepted)​

{
  "queued": true,
  "resolved": {
    "collections": 2,
    "target_tenants": 3
  }
}
FieldTypeDescription
queuedbooleanAlways true on success; sharing has been scheduled
resolved.collectionsintegerNumber of collection values accepted from the request
resolved.target_tenantsintegerNumber of authorized target tenants for which a job was queued
Verifying the Result

The response confirms the request was accepted, not that sharing has finished. Use List Content or Get Content on the receiving tenant to confirm that items have appeared in its catalog.

Error Handling​

Validation Errors (422)​

{
  "message": "The given data was invalid.",
  "errors": {
    "collections": ["Unknown collections: Fall Releases 2026"]
  }
}
{
  "message": "The given data was invalid.",
  "errors": {
    "tenant_ids": ["Not authorized to share with tenants: 87, 153"]
  }
}

Common Validation Causes​

Error messageCause
collections field is requiredMissing collections array
collections may not have more than 50 itemsSent more than 50 collection values
Unknown collections: ...One or more values match neither the name nor the slug of a collection that belongs to your tenant
tenant_ids field is required when tenant_external_ids is not presentNeither tenant identifier list was provided
tenant_ids field prohibits tenant_external_ids from being presentBoth tenant identifier lists were provided
tenant_ids may not have more than 50 itemsSent more than 50 target tenants
Unknown tenant_ids: ...One or more target IDs do not match an existing tenant
Not authorized to share with tenants: ...One or more targets are neither aggregated tenants nor have content_share

Authentication Errors (401)​

{
  "message": "Unauthenticated."
}

Rate Limit Errors (429)​

The endpoint shares the bulk operations rate limiter (10 requests per minute per API token). When exceeded:

{
  "message": "Too Many Attempts."
}

See Also​

X

Graph View