[Bug]: Not possible to set relations via document api

[z0lo13]

Link to the documentation page or resource

https://docs.strapi.io/cms/api/rest/relations

Describe the bug

await strapi
                .documents('api::cart.cart')
                .update({
                    documentId: cart.documentId,
                    data: {
                        state: 'checked_out',
                        orderDocumentId: {
                            connect: [order.documentId]
                        }
                    },
                });

resulst in the following error:

src/api/order/controllers/order.ts:431:60 - error TS2353: Object literal may only specify known properties, and 'connect' does not exist in type 'LongHandEntity | LongHandDocument'.
mir-stekla-back         | 
mir-stekla-back         | 431           data: { state: 'checked_out', orderDocumentId: { connect: [order.documentId] } },
mir-stekla-back         |                                                                ~~~~~~~
mir-stekla-back         | 
mir-stekla-back         | Found 1 error(s).
mir-stekla-back         | 

The metehod is taken from here:
https://docs.strapi.io/cms/api/rest/relations

Additional context

No response

Suggested improvements or fixes

No response

Related issue(s)/PR(s)

No response

[github-actions]

🤖 I've analyzed your question and here's what I found:

Thanks a lot for taking the time to report this and for sharing your code snippet — that really helps understand what you’re trying to do.

You’re on the right track conceptually: relations can be managed with connect, disconnect, and set when using the Document Service API, and the syntax is the same as for the REST API. [Relations API; Document service]

From the docs:

“Relations can also be connected, disconnected, and set through the Document Service API, just like with the REST API (see the REST API relations documentation for examples).” [Document service]

and the example with update():

await strapi.documents('api::restaurant.restaurant').update({   
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',  
  locale: 'fr',  
  data: {   
    category: {  
      connect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']  
    }  
  }  
});

[Relations API]

So your usage:

await strapi
  .documents('api::cart.cart')
  .update({
    documentId: cart.documentId,
    data: {
      state: 'checked_out',
      orderDocumentId: {
        connect: [order.documentId],
      },
    },
  });

is aligned with what the docs describe.

---

Why you’re seeing the TypeScript error

The error:

Object literal may only specify known properties, and 'connect' does not exist in type 'LongHandEntity | LongHandDocument'.

comes from TypeScript’s type definitions, not from the runtime behavior of Strapi itself. The documentation clearly states that connect, disconnect, and set are supported on the Document Service API, but the type you’re getting (LongHandEntity | LongHandDocument) doesn’t seem to expose connect as a valid property. [Relations API; Document service]

In other words:

• Docs: say connect is valid in data for relations when using strapi.documents().update().
• TypeScript types: currently don’t recognize connect on that specific type, which leads to the TS2353 error.

This points to a typing / DX issue, not that the feature itself is unsupported.

---

What you can do right now

Since the docs confirm that connect is supported on the Document Service API, you can:

1. Keep using the documented syntax at runtime (it should work as per the examples above).
2. As a temporary workaround on the TypeScript side, you can:
   • Loosen the typing locally (e.g. via a cast) so you can keep using connect as documented, or
   • Isolate the data object in a variable and cast it to any or a broader type to bypass the incorrect constraint.

Because the knowledge sources don’t include the exact TS type definitions or a fix for them, I can’t point to a specific type change, but the behavior described in the docs is clear.

---

Next steps

This looks like a product / typings bug rather than a documentation-only issue, since the docs and the runtime behavior are aligned but the TypeScript types are not.

I’d recommend:

• Keeping this issue open so it can be reviewed by the core team.
• Potentially transferring it to the main strapi/strapi repository so the typings can be updated accordingly. Tagging for visibility: @pwizla.

In the meantime, you can rely on the documented connect/disconnect/set syntax for relations with the Document Service API and use a small TS workaround to unblock your implementation. [Relations API; Document service]

If you’d like, you can also share your cart and order relation definitions so the team can double‑check that the relation shape matches what the docs expect.

📚 Relevant documentation:

• CRUD operations with the Entity Service API - update()
• Document Service API
• Document Service API - update()
• Document Service API: Populating fields
• GraphQL API - Mutations
• Managing relations with API requests
• Managing relations with API requests - connect
• Managing relations with API requests - disconnect
• Managing relations with API requests - set
• Managing relations with API requests - Edge cases: Draft & Publish or i18n disabled
• Managing relations with API requests - Relations reordering
• Models - Relations
• REST API reference - Update a document

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.