> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/users/module-2/contact.md).

# Contact

Contact us and conversation endpoints

## Submit Contact Us Form

> Submits a contact us message.\
> \
> \*\*Business Logic:\*\*\
> \- \*\*Email Routing:\*\* Sends an email to recipients configured in \`CONTACT\_US\_EMAIL\_TO\` based on the operation type.\
> \- \*\*User Notification:\*\* Optionally sends a copy to the user if \`CONTACT\_US\_SEND\_USER\` is enabled.\
> \- \*\*Reply-To:\*\* Sets the Reply-To header to the user's email if \`CONTACT\_US\_REPLY\_TO\_ONLY\_USER\` is enabled.\
> \- \*\*CC/BCC:\*\* Applies CC/BCC rules from \`EMAIL\_BCC\_AND\_CC\` setting.\
> \- \*\*Attachments:\*\* Validates and attaches files if provided.\
> \- \*\*Order Linking:\*\* Links the message to a specific order if required by the subject.\
> \
> \*\*Dynamic Settings:\*\*\
> \- \`CONTACT\_US\_EMAIL\_TO\`: Dictionary mapping operations to recipient emails.\
> \- \`CONTACT\_US\_SEND\_USER\`: Boolean to enable sending a copy to the user.\
> \- \`CONTACT\_US\_REPLY\_TO\_ONLY\_USER\`: Boolean to set user as the only Reply-To address.\
> \- \`EMAIL\_BCC\_AND\_CC\`: Configuration for CC and BCC recipients.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Contact","description":"Contact us and conversation endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/users/contact-us/":{"post":{"tags":["Contact"],"summary":"Submit Contact Us Form","description":"Submits a contact us message.\n\n**Business Logic:**\n- **Email Routing:** Sends an email to recipients configured in `CONTACT_US_EMAIL_TO` based on the operation type.\n- **User Notification:** Optionally sends a copy to the user if `CONTACT_US_SEND_USER` is enabled.\n- **Reply-To:** Sets the Reply-To header to the user's email if `CONTACT_US_REPLY_TO_ONLY_USER` is enabled.\n- **CC/BCC:** Applies CC/BCC rules from `EMAIL_BCC_AND_CC` setting.\n- **Attachments:** Validates and attaches files if provided.\n- **Order Linking:** Links the message to a specific order if required by the subject.\n\n**Dynamic Settings:**\n- `CONTACT_US_EMAIL_TO`: Dictionary mapping operations to recipient emails.\n- `CONTACT_US_SEND_USER`: Boolean to enable sending a copy to the user.\n- `CONTACT_US_REPLY_TO_ONLY_USER`: Boolean to set user as the only Reply-To address.\n- `EMAIL_BCC_AND_CC`: Configuration for CC and BCC recipients.","operationId":"submitContactUs","parameters":[{"$ref":"#/components/parameters/CSRFTokenHeader"},{"$ref":"#/components/parameters/CookieHeader"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ContactUsRequest"}}}},"responses":{"200":{"description":"Message sent successfully"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}}},"components":{"parameters":{"CSRFTokenHeader":{"name":"X-CSRFToken","in":"header","description":"CSRF token for write operations (POST, PUT, PATCH, DELETE).\nRequired for security when using session authentication.\nObtain token from cookie 'csrftoken' or meta tag in HTML.","required":true,"schema":{"type":"string"}},"CookieHeader":{"name":"Cookie","in":"header","description":"Session ID and CSRF token cookies.\nFormat: `sessionid=<id>; osessionid=<id>; csrftoken=<token>`","required":true,"schema":{"type":"string"}}},"schemas":{"ContactUsRequest":{"type":"object","required":["subject","full_name","email","message"],"properties":{"subject":{"type":"integer","description":"ID of the contact subject. Determines if an order reference is required."},"full_name":{"type":"string","maxLength":70},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":70},"message":{"type":"string"},"file":{"type":"string","format":"binary","description":"Optional file attachment. Validated for allowed extensions and size limits."},"order":{"type":"integer","description":"ID of the related order. Required if the selected subject implies an order context. Must belong to the authenticated user."},"operation":{"type":"string","maxLength":30,"description":"Operation type key. Validated against configured contact email recipients (`CONTACT_US_EMAIL_TO`)."}}},"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}
```

## List Contact Us Subjects

> Lists available subjects for the contact us form.\
> \
> \*\*Business Logic:\*\*\
> \- Returns subjects localized to the current language.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Contact","description":"Contact us and conversation endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/users/contact-us-subjects/":{"get":{"tags":["Contact"],"summary":"List Contact Us Subjects","description":"Lists available subjects for the contact us form.\n\n**Business Logic:**\n- Returns subjects localized to the current language.","operationId":"listContactUsSubjects","responses":{"200":{"description":"List of subjects","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ContactUsSubject"}}}}}}}}},"components":{"schemas":{"ContactUsSubject":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the contact subject."},"text":{"type":"string","description":"Localized subject text."},"is_order_needed":{"type":"boolean","description":"Indicates if an order ID is required for this subject."}}}}}}
```

## List Conversations

> Lists the authenticated user's own conversations: private messages, product questions and product reviews.\
> \
> \*\*Business Logic:\*\*\
> \- Only the caller's own conversations are returned, in every moderation state. Reviews and questions that are still \`pending\` or were \`rejected\` are included, so the storefront can show the author where each post stands.\
> \- Results are paginated (\`page\`, \`limit\`; 10 per page by default) and ordered by \`last\_message\_date\`, newest first.\
> \- Each conversation carries its star \`rating\` (reviews only) and its moderation \`status\`. The moderation audit trail is not part of this response.\
> \- \`is\_public\` becomes \`true\` only when a moderator approves a review or question; a private message is never made public. Conversations created before moderation existed keep the visibility they had.\
> \- Reads count towards the same \`send-message\` rate limit as posting.\
> \
> \*\*Filters:\*\*\
> \- \`product\` and \`product\_base\_code\` match any conversation on the order items that sold the product (private messages included) \*\*plus\*\* conversations anchored to the product itself.\
> \- Date ranges are also accepted: \`created\_date\_\_gt|gte|lt|lte\`, \`modified\_date\_\_gt|gte|lt|lte\` and \`last\_message\_date\_\_gt|gte|lt|lte\` (ISO 8601 date-time).

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Contact","description":"Contact us and conversation endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"cookieAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"parameters":{"PageParameter":{"name":"page","in":"query","required":false,"description":"Page number (1-indexed).","schema":{"type":"integer","minimum":1}},"LimitParameter":{"name":"limit","in":"query","required":false,"description":"Number of results per page (default 10).","schema":{"type":"integer","minimum":1}},"ConversationTypeParameter":{"name":"conversation_type","in":"query","required":false,"description":"Filter by conversation kind.","schema":{"type":"string","enum":["message","question","review"]}},"ConversationStatusParameter":{"name":"status","in":"query","required":false,"description":"Filter by moderation status. Private messages and conversations created before moderation existed have no status and are not matched by any value.","schema":{"type":"string","enum":["pending","approved","rejected"]}},"ConversationProductParameter":{"name":"product","in":"query","required":false,"description":"Product ID. Matches any conversation on the order items that sold this product (private messages included) plus conversations anchored to the product itself. A value that is not a number is rejected with `400`.","schema":{"type":"integer"}},"ConversationProductBaseCodeParameter":{"name":"product_base_code","in":"query","required":false,"description":"Product base code. Matches any conversation on the order items that sold a product with this base code (private messages included) plus conversations anchored to any of those products.","schema":{"type":"string"}},"ConversationOrderItemParameter":{"name":"order_item","in":"query","required":false,"description":"Order item ID. Matches conversations about this order item. A value that is not a number is rejected with `400`.","schema":{"type":"integer"}},"ConversationOrderNumberParameter":{"name":"order_number","in":"query","required":false,"description":"Order number. Matches conversations about any order item of this order.","schema":{"type":"string"}},"ConversationItemTypeParameter":{"name":"item_type","in":"query","required":false,"description":"Filter by the kind of item the conversation is about.","schema":{"type":"string","enum":["product","orderitem"]}},"ConversationIsPublicParameter":{"name":"is_public","in":"query","required":false,"description":"Filter by storefront visibility.","schema":{"type":"boolean"}},"ConversationIsAnsweredParameter":{"name":"is_answered","in":"query","required":false,"description":"Filter by whether the seller has answered.","schema":{"type":"boolean"}},"ConversationDataSourceParameter":{"name":"data_source","in":"query","required":false,"description":"Seller slug.","schema":{"type":"string"}},"ConversationDataSourceIdParameter":{"name":"data_source_id","in":"query","required":false,"description":"Seller ID.","schema":{"type":"integer"}}},"schemas":{"PaginatedConversationList":{"type":"object","description":"Paginated list of the caller's conversations.","required":["count","next","previous","results"],"properties":{"count":{"type":"integer","description":"Total number of matching conversations."},"next":{"type":["string","null"],"format":"uri","description":"URL of the next page, or `null` on the last page."},"previous":{"type":["string","null"],"format":"uri","description":"URL of the previous page, or `null` on the first page."},"results":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}}},"Conversation":{"type":"object","description":"A conversation as its owner sees it, with the owner's own contact data. The moderation audit trail is not included.","properties":{"id":{"type":"integer","description":"Unique identifier for the conversation."},"subject":{"type":["string","null"],"description":"The subject of the conversation. `null` when none was sent."},"user":{"$ref":"#/components/schemas/UserMessage","description":"The user associated with the conversation."},"datasource":{"$ref":"#/components/schemas/DataSource","description":"The seller the conversation is with."},"item_object":{"type":["object","null"],"description":"Details of the related item. Structure depends on `item_content`:\n- `orderitem`: `{pk, product, status, order_number}`, where `product` is `{pk, name, sku, absolute_url, product_images}` and `status` is the order item's status code (e.g. `\"550\"` = delivered).\n- `product`: `{pk, name, sku, absolute_url, product_images}`.\n- `null` when the conversation is not about an item."},"item_content":{"type":["string","null"],"enum":["product","orderitem",null],"description":"Kind of item the conversation is about. New reviews always use `orderitem`, new questions `product` (or none), new private messages `orderitem` (or none). Conversations created before these rules may differ."},"message_set":{"type":"array","items":{"$ref":"#/components/schemas/Message"},"description":"Messages in the conversation, newest first."},"conversation_type":{"type":"string","enum":["message","question","review"],"description":"The type of conversation."},"last_message_date":{"type":"string","format":"date-time","description":"Timestamp of the last message in the conversation."},"is_public":{"type":"boolean","description":"`true` once a moderator has approved the review or question; it is then listed on `/public-reviews/` or `/public-questions/`. Always `false` for a private message. Conversations created before moderation existed keep the visibility they had."},"is_answered":{"type":"boolean","description":"Indicates if the conversation has been answered."},"rating":{"type":["integer","null"],"minimum":1,"maximum":5,"description":"Star rating from 1 to 5 on a review. `null` on questions, private messages and reviews written before ratings existed."},"status":{"$ref":"#/components/schemas/ConversationStatus"}}},"UserMessage":{"type":"object","properties":{"id":{"type":"integer","description":"User ID."},"first_name":{"type":"string","description":"User's first name."},"last_name":{"type":"string","description":"User's last name."},"email":{"type":"string","description":"User's email address."},"phone":{"type":["string","null"],"description":"User's phone number."},"gender":{"type":["string","null"],"enum":["male","female","not_to_say",null],"description":"User's gender."}}},"DataSource":{"type":"object","description":"The seller a conversation is with.","properties":{"pk":{"type":"integer","description":"Seller ID."},"name":{"type":["string","null"],"description":"Name of the seller."},"slug":{"type":["string","null"],"description":"Seller slug (used by the `data_source` filter)."},"title":{"type":["string","null"],"description":"Seller's display title."},"supplier_code":{"type":"string","description":"Supplier code of the seller."},"address":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"phone_number":{"type":["string","null"]},"fax_number":{"type":["string","null"]},"kep_address":{"type":["string","null"],"format":"email"},"mersis_number":{"type":["string","null"]},"trade_association":{"type":["string","null"]},"extras":{"type":["object","null"],"description":"Free-form seller data."},"price_list":{"type":["integer","null"],"description":"ID of the seller's price list."},"stock_list":{"type":["integer","null"],"description":"ID of the seller's stock list."},"is_active":{"type":"boolean"}}},"Message":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the message."},"message_content":{"type":"string","description":"The content of the message."},"user_type":{"type":["string","null"],"enum":["guest","registered",null],"description":"The type of user who sent the message."},"content_object":{"$ref":"#/components/schemas/MessageContent","description":"Details of the sender (User or DataSource)."},"content_type":{"type":"string","description":"The type of the sender (e.g., 'user', 'datasource')."},"created_date":{"type":"string","format":"date-time","description":"Timestamp when the message was created."}}},"MessageContent":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the sender."},"email":{"type":"string","description":"Email of the sender."},"first_name":{"type":"string","description":"First name of the sender."},"last_name":{"type":"string","description":"Last name of the sender."},"phone":{"type":"string","description":"Phone number of the sender."},"gender":{"type":["string","null"],"description":"Gender of the sender, as its display label in the request language (e.g. `female`, or `kadın` in Turkish; `Prefer not to say` for `not_to_say`), not the enum value."},"name":{"type":"string","description":"Name of the sender (if DataSource)."},"title":{"type":"string","description":"Title of the sender (if applicable)."}}},"ConversationStatus":{"type":["string","null"],"enum":["pending","approved","rejected",null],"description":"Moderation state of a review or question:\n- `pending`: waiting for a moderator; not public.\n- `approved`: published on the storefront (`is_public: true`).\n- `rejected`: turned down by a moderator; not public. The author is e-mailed the reason, unless the brand has disabled that e-mail. The author may post again.\n- `null`: private messages (never moderated) and conversations created before moderation existed."},"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}},"DetailErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication credentials were not provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}},"Throttled":{"description":"Request was throttled (scope rate limit exceeded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}}}},"paths":{"/users/conversations/":{"get":{"tags":["Contact"],"summary":"List Conversations","description":"Lists the authenticated user's own conversations: private messages, product questions and product reviews.\n\n**Business Logic:**\n- Only the caller's own conversations are returned, in every moderation state. Reviews and questions that are still `pending` or were `rejected` are included, so the storefront can show the author where each post stands.\n- Results are paginated (`page`, `limit`; 10 per page by default) and ordered by `last_message_date`, newest first.\n- Each conversation carries its star `rating` (reviews only) and its moderation `status`. The moderation audit trail is not part of this response.\n- `is_public` becomes `true` only when a moderator approves a review or question; a private message is never made public. Conversations created before moderation existed keep the visibility they had.\n- Reads count towards the same `send-message` rate limit as posting.\n\n**Filters:**\n- `product` and `product_base_code` match any conversation on the order items that sold the product (private messages included) **plus** conversations anchored to the product itself.\n- Date ranges are also accepted: `created_date__gt|gte|lt|lte`, `modified_date__gt|gte|lt|lte` and `last_message_date__gt|gte|lt|lte` (ISO 8601 date-time).","operationId":"listConversations","parameters":[{"$ref":"#/components/parameters/PageParameter"},{"$ref":"#/components/parameters/LimitParameter"},{"$ref":"#/components/parameters/ConversationTypeParameter"},{"$ref":"#/components/parameters/ConversationStatusParameter"},{"$ref":"#/components/parameters/ConversationProductParameter"},{"$ref":"#/components/parameters/ConversationProductBaseCodeParameter"},{"$ref":"#/components/parameters/ConversationOrderItemParameter"},{"$ref":"#/components/parameters/ConversationOrderNumberParameter"},{"$ref":"#/components/parameters/ConversationItemTypeParameter"},{"$ref":"#/components/parameters/ConversationIsPublicParameter"},{"$ref":"#/components/parameters/ConversationIsAnsweredParameter"},{"$ref":"#/components/parameters/ConversationDataSourceParameter"},{"$ref":"#/components/parameters/ConversationDataSourceIdParameter"}],"responses":{"200":{"description":"Paginated list of the caller's conversations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedConversationList"}}}},"400":{"description":"A filter value is invalid, for example a `product` or `order_item` that is not a number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/Throttled"}}}}}}
```

## Create Conversation

> Opens a new conversation with its first message, or adds a message to one of the caller's own private message threads.\
> \
> The customer always writes in their own name: \`user\` and \`content\_id\` must be the authenticated user's ID and \`content\_type\` must be \`user\`.\
> \
> \*\*Conversation kinds:\*\*\
> \
> \| \`conversation\_type\` | Moderated | \`rating\` | Allowed \`item\_content\` | Customer may add more messages |\
> \|---|---|---|---|---|\
> \| \`review\` | Yes | Required, 1–5 | \`orderitem\` (required) | No |\
> \| \`question\` | Yes | Not allowed | \`product\` (optional) | No |\
> \| \`message\` | No | Not allowed | \`orderitem\` (optional) | Yes |\
> \
> \`item\_content\` is checked only when it is sent. An \`orderitem\` must belong to one of the caller's orders, for any kind. The item must exist, and when it names a seller — an order item's seller (or, failing that, its product's), a product's seller — that seller must be the \`datasource\` sent. An item that names no seller, as on a single-seller storefront, is accepted with any \`datasource\`.\
> \
> \*\*Business Logic:\*\*\
> \- \*\*Visibility follows moderation:\*\* \`is\_public\` in the request is ignored. Every new conversation is created with \`is\_public: false\`. A review or question starts as \`status: pending\` and is listed on \`/public-reviews/\` or \`/public-questions/\` only after a moderator approves it. A private message has \`status: null\` and is never public.\
> \- \*\*Reviews:\*\* a review names the order item it is about (\`item\_content: orderitem\` + \`item\_id\`), carries a \`rating\` from 1 to 5 and needs text in \`message\_content\`. By default the order item must be delivered (see \`REVIEW\_REQUIRES\_PURCHASE\`).\
> \- \*\*One review per purchase:\*\* if the caller already has a review on the same order item that was not rejected (pending, approved, or written before moderation existed), a new one is refused. After a rejection the customer may write a new review for that order item.\
> \- \*\*Adding to a thread:\*\* send \`conversation\` with the ID of one of your own private message threads to add a message instead of opening a new one. Reviews and questions are written once, so adding to them is refused. The existing thread keeps its own kind, subject, item and rating: those fields in the body are not applied, and the conversation fields in the response are the thread's. A customer message on an answered private thread marks it unanswered again.\
> \- \*\*Duplicates:\*\* opening a conversation identical to one of your own (same seller, subject, kind and item) is refused with \`406\` and \`error\_code: conversation\_100\_1\`, whether the existing one is published or not. Only a rejected conversation does not count.\
> \- \*\*Rate limit:\*\* requests count towards the \`send-message\` limit; over the limit the response is \`429\` (the first request over it from a client not yet flagged is let through once).\
> \
> \*\*Dynamic Settings:\*\*\
> \- \`REVIEW\_REQUIRES\_PURCHASE\` (default \`true\`): a review is accepted only when its order item is in the delivered status (\`550\`); one not yet delivered, or since refunded (\`600\`), is refused. With \`false\` the delivery check is skipped, so an order item that was bought but not yet delivered can be reviewed. Ownership of the order item, the rating and the one-review-per-purchase rule still apply. Questions and private messages ignore this setting.\
> \
> \*\*Errors:\*\*\
> Error messages are translated to the request language, so match on the status and the error key or code, not on the text.\
> \- \`400\` — the request itself is invalid: field errors as \`{"\<field>": \["\<message>"]}\`, the order-item ownership check on \`item\_id\`, and the author and review checks as \`{"non\_field\_errors": \["\<message>"]}\`.\
> \- \`406\` — a conversation rule refuses it: \`{"non\_field\_errors": "\<message>", "error\_code": "\<code>"}\`, with the message as a single string. Branch on \`error\_code\`:\
> \
> \| \`error\_code\` | Refused because |\
> \|---|---|\
> \| \`conversation\_100\_1\` | An identical conversation already exists. |\
> \| \`conversation\_100\_5\` | The \`item\_content\` is not allowed for the \`conversation\_type\`. |\
> \| \`conversation\_100\_6\` | A review was sent without a \`rating\`. |\
> \| \`conversation\_100\_7\` | A \`rating\` was sent with a question or a private message. |\
> \| \`conversation\_100\_10\` | A message was added to a review or a question. |\
> \| \`conversation\_100\_12\` | The product does not exist. An order item that does not exist is answered like one that is not yours, with \`400\` on \`item\_id\`. |\
> \| \`conversation\_100\_13\` | The item belongs to a seller other than \`datasource\`. |

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Contact","description":"Contact us and conversation endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"cookieAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"parameters":{"CSRFTokenHeader":{"name":"X-CSRFToken","in":"header","description":"CSRF token for write operations (POST, PUT, PATCH, DELETE).\nRequired for security when using session authentication.\nObtain token from cookie 'csrftoken' or meta tag in HTML.","required":true,"schema":{"type":"string"}},"CookieHeader":{"name":"Cookie","in":"header","description":"Session ID and CSRF token cookies.\nFormat: `sessionid=<id>; osessionid=<id>; csrftoken=<token>`","required":true,"schema":{"type":"string"}}},"schemas":{"CreateConversationRequest":{"type":"object","required":["message_content","user_type","content_id","content_type","datasource","user","conversation_type"],"properties":{"message_content":{"type":"string","minLength":1,"maxLength":500,"description":"The body of the message. For a review, the review text; for a question, the question. May not be blank."},"user_type":{"type":"string","enum":["guest","registered"],"description":"Type of user creating the conversation."},"content_id":{"type":"integer","minimum":1,"description":"ID of the message author. Must be the authenticated user's ID."},"content_type":{"type":"string","enum":["user","datasource"],"description":"Author type of the message. Must be `user` on this endpoint; `datasource` is refused with `Users do not match.`"},"conversation":{"type":"integer","description":"ID of one of your own **private message** threads to add this message to. Omit it to open a new conversation. Reviews and questions do not accept further messages. An ID that does not exist is refused with `400` on `conversation` (`Invalid pk \"<id>\" - object does not exist.`)."},"datasource":{"type":"integer","description":"ID of the seller the conversation is with."},"user":{"type":"integer","description":"ID of the user who owns the conversation. Must be the authenticated user's ID."},"subject":{"type":"string","maxLength":500,"description":"Subject of the conversation."},"item_content":{"type":"string","enum":["product","orderitem"],"description":"Kind of item the conversation is about. Allowed per kind: `review` → `orderitem` only (required); `question` → `product` only; `message` → `orderitem` only. Optional for questions and messages."},"item_id":{"type":"integer","minimum":1,"description":"ID of the order item or product named in `item_content`. Required for a review. It must exist, an order item must belong to one of your orders, and an item that names a seller must belong to `datasource`."},"conversation_type":{"type":"string","enum":["message","question","review"],"description":"Type of conversation."},"rating":{"type":"integer","minimum":1,"maximum":5,"description":"Star rating from 1 to 5. Required when `conversation_type` is `review`; refused for `question` and `message`."},"is_public":{"type":"boolean","readOnly":true,"description":"Ignored if sent. Visibility follows moderation: every new conversation is created with `is_public: false`, and only a moderator's approval publishes a review or question."}},"description":"Request body for creating a conversation or message.\n\n**Validation:**\n- Users must match the authenticated user and content owner: `user` and `content_id` are the caller's ID, `content_type` is `user`, and `conversation` (when sent) is one of the caller's threads.\n- `rating` is required on a review and refused on a question or private message.\n- `item_content` must be allowed for the kind (see the table on the endpoint). An `orderitem` must belong to one of the caller's orders.\n- The item must exist, and an item that names a seller must belong to `datasource`.\n- A review must name an order item (`item_content: orderitem` + `item_id`). By default that order item must be delivered (`REVIEW_REQUIRES_PURCHASE`).\n- One review per order item: a review of it that was not rejected (pending, approved, or written before moderation existed) blocks a new one; a rejected one does not.\n- Only private messages accept further customer messages through `conversation`.\n- An identical conversation (same seller, subject, kind and item) may exist only once, published or not; a rejected one does not count.\n\nThe kind and item, rating, item existence and seller, add-to-thread and duplicate rules answer `406` with an `error_code`; field validation and the author, order-item ownership and review checks answer `400` (see the endpoint)."},"CreateConversationResponse":{"type":"object","description":"Echo of the stored message and its conversation. `id` is the **conversation** ID, not the message ID; send it as `conversation` to add to a private message thread. When a message is added to an existing thread, the conversation fields (`subject`, `item_content`, `item_id`, `conversation_type`, `rating`, …) are the thread's.","properties":{"id":{"type":"integer","description":"Conversation ID."},"datasource":{"type":"integer","description":"Seller ID."},"user":{"type":"integer","description":"ID of the user who owns the conversation."},"subject":{"type":["string","null"]},"item_content":{"type":["string","null"],"enum":["product","orderitem",null]},"is_public":{"type":"boolean","description":"Always `false` for a new conversation; approval by a moderator is what publishes a review or question."},"item_id":{"type":["integer","null"]},"conversation_type":{"type":"string","enum":["message","question","review"]},"message_content":{"type":"string"},"user_type":{"type":"string","enum":["guest","registered"]},"content_id":{"type":"integer","description":"ID of the message author."},"content_type":{"type":"string","description":"Author type of the message (`user`)."},"rating":{"type":["integer","null"],"minimum":1,"maximum":5,"description":"The stored star rating; `null` for questions and private messages."}}},"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}},"DetailErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}}},"CodedErrorResponse":{"type":"object","description":"Business-error payload, returned with HTTP 406. `error_code` is stable —\nbranch on it, not on the translated message.","properties":{"non_field_errors":{"type":"string"},"error_code":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication credentials were not provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}},"Throttled":{"description":"Request was throttled (scope rate limit exceeded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}}}},"paths":{"/users/conversations/":{"post":{"tags":["Contact"],"summary":"Create Conversation","description":"Opens a new conversation with its first message, or adds a message to one of the caller's own private message threads.\n\nThe customer always writes in their own name: `user` and `content_id` must be the authenticated user's ID and `content_type` must be `user`.\n\n**Conversation kinds:**\n\n| `conversation_type` | Moderated | `rating` | Allowed `item_content` | Customer may add more messages |\n|---|---|---|---|---|\n| `review` | Yes | Required, 1–5 | `orderitem` (required) | No |\n| `question` | Yes | Not allowed | `product` (optional) | No |\n| `message` | No | Not allowed | `orderitem` (optional) | Yes |\n\n`item_content` is checked only when it is sent. An `orderitem` must belong to one of the caller's orders, for any kind. The item must exist, and when it names a seller — an order item's seller (or, failing that, its product's), a product's seller — that seller must be the `datasource` sent. An item that names no seller, as on a single-seller storefront, is accepted with any `datasource`.\n\n**Business Logic:**\n- **Visibility follows moderation:** `is_public` in the request is ignored. Every new conversation is created with `is_public: false`. A review or question starts as `status: pending` and is listed on `/public-reviews/` or `/public-questions/` only after a moderator approves it. A private message has `status: null` and is never public.\n- **Reviews:** a review names the order item it is about (`item_content: orderitem` + `item_id`), carries a `rating` from 1 to 5 and needs text in `message_content`. By default the order item must be delivered (see `REVIEW_REQUIRES_PURCHASE`).\n- **One review per purchase:** if the caller already has a review on the same order item that was not rejected (pending, approved, or written before moderation existed), a new one is refused. After a rejection the customer may write a new review for that order item.\n- **Adding to a thread:** send `conversation` with the ID of one of your own private message threads to add a message instead of opening a new one. Reviews and questions are written once, so adding to them is refused. The existing thread keeps its own kind, subject, item and rating: those fields in the body are not applied, and the conversation fields in the response are the thread's. A customer message on an answered private thread marks it unanswered again.\n- **Duplicates:** opening a conversation identical to one of your own (same seller, subject, kind and item) is refused with `406` and `error_code: conversation_100_1`, whether the existing one is published or not. Only a rejected conversation does not count.\n- **Rate limit:** requests count towards the `send-message` limit; over the limit the response is `429` (the first request over it from a client not yet flagged is let through once).\n\n**Dynamic Settings:**\n- `REVIEW_REQUIRES_PURCHASE` (default `true`): a review is accepted only when its order item is in the delivered status (`550`); one not yet delivered, or since refunded (`600`), is refused. With `false` the delivery check is skipped, so an order item that was bought but not yet delivered can be reviewed. Ownership of the order item, the rating and the one-review-per-purchase rule still apply. Questions and private messages ignore this setting.\n\n**Errors:**\nError messages are translated to the request language, so match on the status and the error key or code, not on the text.\n- `400` — the request itself is invalid: field errors as `{\"<field>\": [\"<message>\"]}`, the order-item ownership check on `item_id`, and the author and review checks as `{\"non_field_errors\": [\"<message>\"]}`.\n- `406` — a conversation rule refuses it: `{\"non_field_errors\": \"<message>\", \"error_code\": \"<code>\"}`, with the message as a single string. Branch on `error_code`:\n\n| `error_code` | Refused because |\n|---|---|\n| `conversation_100_1` | An identical conversation already exists. |\n| `conversation_100_5` | The `item_content` is not allowed for the `conversation_type`. |\n| `conversation_100_6` | A review was sent without a `rating`. |\n| `conversation_100_7` | A `rating` was sent with a question or a private message. |\n| `conversation_100_10` | A message was added to a review or a question. |\n| `conversation_100_12` | The product does not exist. An order item that does not exist is answered like one that is not yours, with `400` on `item_id`. |\n| `conversation_100_13` | The item belongs to a seller other than `datasource`. |","operationId":"createConversation","parameters":[{"$ref":"#/components/parameters/CSRFTokenHeader"},{"$ref":"#/components/parameters/CookieHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConversationRequest"}}}},"responses":{"201":{"description":"Conversation created (or message added to a private message thread)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConversationResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"406":{"description":"A conversation rule refuses the request. The message is translated and names the conversation kind and the item by their API values (`review`, `question`, `message`; `orderitem`, `product`); branch on `error_code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodedErrorResponse"}}}},"429":{"$ref":"#/components/responses/Throttled"}}}}}}
```

## Retrieve Conversation

> Retrieves details of a specific conversation.\
> \
> \*\*Business Logic:\*\*\
> \- Only the caller's own conversations can be retrieved; another customer's conversation returns \`404\`.\
> \- The response has the same shape as a list item, including \`rating\` and \`status\`. The moderation audit trail is not included.\
> \- Reads count towards the \`send-message\` rate limit.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Contact","description":"Contact us and conversation endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"cookieAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"Conversation":{"type":"object","description":"A conversation as its owner sees it, with the owner's own contact data. The moderation audit trail is not included.","properties":{"id":{"type":"integer","description":"Unique identifier for the conversation."},"subject":{"type":["string","null"],"description":"The subject of the conversation. `null` when none was sent."},"user":{"$ref":"#/components/schemas/UserMessage","description":"The user associated with the conversation."},"datasource":{"$ref":"#/components/schemas/DataSource","description":"The seller the conversation is with."},"item_object":{"type":["object","null"],"description":"Details of the related item. Structure depends on `item_content`:\n- `orderitem`: `{pk, product, status, order_number}`, where `product` is `{pk, name, sku, absolute_url, product_images}` and `status` is the order item's status code (e.g. `\"550\"` = delivered).\n- `product`: `{pk, name, sku, absolute_url, product_images}`.\n- `null` when the conversation is not about an item."},"item_content":{"type":["string","null"],"enum":["product","orderitem",null],"description":"Kind of item the conversation is about. New reviews always use `orderitem`, new questions `product` (or none), new private messages `orderitem` (or none). Conversations created before these rules may differ."},"message_set":{"type":"array","items":{"$ref":"#/components/schemas/Message"},"description":"Messages in the conversation, newest first."},"conversation_type":{"type":"string","enum":["message","question","review"],"description":"The type of conversation."},"last_message_date":{"type":"string","format":"date-time","description":"Timestamp of the last message in the conversation."},"is_public":{"type":"boolean","description":"`true` once a moderator has approved the review or question; it is then listed on `/public-reviews/` or `/public-questions/`. Always `false` for a private message. Conversations created before moderation existed keep the visibility they had."},"is_answered":{"type":"boolean","description":"Indicates if the conversation has been answered."},"rating":{"type":["integer","null"],"minimum":1,"maximum":5,"description":"Star rating from 1 to 5 on a review. `null` on questions, private messages and reviews written before ratings existed."},"status":{"$ref":"#/components/schemas/ConversationStatus"}}},"UserMessage":{"type":"object","properties":{"id":{"type":"integer","description":"User ID."},"first_name":{"type":"string","description":"User's first name."},"last_name":{"type":"string","description":"User's last name."},"email":{"type":"string","description":"User's email address."},"phone":{"type":["string","null"],"description":"User's phone number."},"gender":{"type":["string","null"],"enum":["male","female","not_to_say",null],"description":"User's gender."}}},"DataSource":{"type":"object","description":"The seller a conversation is with.","properties":{"pk":{"type":"integer","description":"Seller ID."},"name":{"type":["string","null"],"description":"Name of the seller."},"slug":{"type":["string","null"],"description":"Seller slug (used by the `data_source` filter)."},"title":{"type":["string","null"],"description":"Seller's display title."},"supplier_code":{"type":"string","description":"Supplier code of the seller."},"address":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"phone_number":{"type":["string","null"]},"fax_number":{"type":["string","null"]},"kep_address":{"type":["string","null"],"format":"email"},"mersis_number":{"type":["string","null"]},"trade_association":{"type":["string","null"]},"extras":{"type":["object","null"],"description":"Free-form seller data."},"price_list":{"type":["integer","null"],"description":"ID of the seller's price list."},"stock_list":{"type":["integer","null"],"description":"ID of the seller's stock list."},"is_active":{"type":"boolean"}}},"Message":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the message."},"message_content":{"type":"string","description":"The content of the message."},"user_type":{"type":["string","null"],"enum":["guest","registered",null],"description":"The type of user who sent the message."},"content_object":{"$ref":"#/components/schemas/MessageContent","description":"Details of the sender (User or DataSource)."},"content_type":{"type":"string","description":"The type of the sender (e.g., 'user', 'datasource')."},"created_date":{"type":"string","format":"date-time","description":"Timestamp when the message was created."}}},"MessageContent":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the sender."},"email":{"type":"string","description":"Email of the sender."},"first_name":{"type":"string","description":"First name of the sender."},"last_name":{"type":"string","description":"Last name of the sender."},"phone":{"type":"string","description":"Phone number of the sender."},"gender":{"type":["string","null"],"description":"Gender of the sender, as its display label in the request language (e.g. `female`, or `kadın` in Turkish; `Prefer not to say` for `not_to_say`), not the enum value."},"name":{"type":"string","description":"Name of the sender (if DataSource)."},"title":{"type":"string","description":"Title of the sender (if applicable)."}}},"ConversationStatus":{"type":["string","null"],"enum":["pending","approved","rejected",null],"description":"Moderation state of a review or question:\n- `pending`: waiting for a moderator; not public.\n- `approved`: published on the storefront (`is_public: true`).\n- `rejected`: turned down by a moderator; not public. The author is e-mailed the reason, unless the brand has disabled that e-mail. The author may post again.\n- `null`: private messages (never moderated) and conversations created before moderation existed."},"DetailErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication credentials were not provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}},"Throttled":{"description":"Request was throttled (scope rate limit exceeded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}}}},"paths":{"/users/conversations/{id}/":{"get":{"tags":["Contact"],"summary":"Retrieve Conversation","description":"Retrieves details of a specific conversation.\n\n**Business Logic:**\n- Only the caller's own conversations can be retrieved; another customer's conversation returns `404`.\n- The response has the same shape as a list item, including `rating` and `status`. The moderation audit trail is not included.\n- Reads count towards the `send-message` rate limit.","operationId":"getConversation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Conversation ID"}],"responses":{"200":{"description":"Conversation details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"No conversation with this ID belongs to the caller. Another customer's conversation is answered the same way as one that does not exist. An ID that is not a number is answered with `Not found.` instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}},"429":{"$ref":"#/components/responses/Throttled"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/users/module-2/contact.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
