Message buyer about order

curl --request POST \
  --url https://{host}/v1/sellers/{sellerId}/orders/{orderId}/conversation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '
{
  "data": {
    "type": "conversations",
    "attributes": {
      "message": "When will my watch be shipped?"
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/vnd.api+json'},
  body: JSON.stringify({
    data: {type: 'conversations', attributes: {message: 'When will my watch be shipped?'}}
  })
};

fetch('https://{host}/v1/sellers/{sellerId}/orders/{orderId}/conversation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/v1/sellers/{sellerId}/orders/{orderId}/conversation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'type' => 'conversations',
        'attributes' => [
                'message' => 'When will my watch be shipped?'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/vnd.api+json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://{host}/v1/sellers/{sellerId}/orders/{orderId}/conversation"

payload = { "data": {
        "type": "conversations",
        "attributes": { "message": "When will my watch be shipped?" }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/vnd.api+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "type": "conversations",
    "id": "3312",
    "attributes": {
      "side": "seller",
      "unread": true,
      "archived": false,
      "noReplyNeeded": false,
      "buyer": {
        "name": "Jens Urlbauer",
        "initials": "JU",
        "estimatedCountry": "DE"
      },
      "blocked": false,
      "blockedByYou": false,
      "purpose": "propose_price",
      "lastMessage": {
        "id": "88120",
        "excerpt": "Price proposal",
        "from": "seller",
        "mine": false,
        "createdAt": "2026-09-21T09:30:11+02:00",
        "removed": false,
        "priceProposal": {
          "amount": 1300000,
          "currency": "EUR",
          "from": "seller",
          "status": "pending",
          "open": true,
          "payable": true,
          "generatedBody": true
        }
      },
      "agreedPrice": 1300000,
      "order": null,
      "createdAt": "2026-09-20T10:00:00.000000Z",
      "updatedAt": "2026-09-21T07:30:11.000000Z"
    },
    "relationships": {
      "watch": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/watch"
        }
      },
      "seller": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/seller"
        }
      },
      "messages": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/messages"
        }
      }
    },
    "links": {
      "self": "https://api.wristler.eu/v1/conversations/3312"
    }
  }
}

{
  "data": {
    "type": "conversations",
    "id": "3312",
    "attributes": {
      "side": "seller",
      "unread": true,
      "archived": false,
      "noReplyNeeded": false,
      "buyer": {
        "name": "Jens Urlbauer",
        "initials": "JU",
        "estimatedCountry": "DE"
      },
      "blocked": false,
      "blockedByYou": false,
      "purpose": "propose_price",
      "lastMessage": {
        "id": "88120",
        "excerpt": "Price proposal",
        "from": "seller",
        "mine": false,
        "createdAt": "2026-09-21T09:30:11+02:00",
        "removed": false,
        "priceProposal": {
          "amount": 1300000,
          "currency": "EUR",
          "from": "seller",
          "status": "pending",
          "open": true,
          "payable": true,
          "generatedBody": true
        }
      },
      "agreedPrice": 1300000,
      "order": null,
      "createdAt": "2026-09-20T10:00:00.000000Z",
      "updatedAt": "2026-09-21T07:30:11.000000Z"
    },
    "relationships": {
      "watch": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/watch"
        }
      },
      "seller": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/seller"
        }
      },
      "messages": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/messages"
        }
      }
    },
    "links": {
      "self": "https://api.wristler.eu/v1/conversations/3312"
    }
  }
}

{
  "errors": [
    {
      "status": "404",
      "code": "watch_reserved",
      "title": "Not Found",
      "detail": "<string>",
      "meta": {},
      "source": {
        "pointer": "/data/attributes/reference",
        "parameter": "<string>"
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

{
  "errors": [
    {
      "status": "404",
      "code": "watch_reserved",
      "title": "Not Found",
      "detail": "<string>",
      "meta": {},
      "source": {
        "pointer": "/data/attributes/reference",
        "parameter": "<string>"
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

{
  "errors": [
    {
      "status": "404",
      "code": "watch_reserved",
      "title": "Not Found",
      "detail": "<string>",
      "meta": {},
      "source": {
        "pointer": "/data/attributes/reference",
        "parameter": "<string>"
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

Messaging

Message buyer about order

Scope: messages:write

The shop’s “message the buyer” about one of its own orders; another shop’s order answers 404.

{ "data": { "type": "conversations",
            "attributes": { "message": "When will my watch be shipped?" } } }

It works when the listing is gone. After a sale the listing is often deleted, and POST /v1/conversations — which starts a thread about a listing — can no longer be used. This finds the thread through the order instead: the one about the order’s watch that the buyer and the shop already have, or a new one (purpose: aftercare). Asking again writes into the same thread. The website’s order pages do exactly this.

message is required, at least 6 characters — the website’s rule. It is sent like any message: read for you, unread for the other side, and they are told about it.

Answers the thread — 201 when it is new, 200 when it was already there — so the app can open it. An order that kept no listing at all, deleted or not (only very old ones), is 422 order_has_no_listing; an order whose buyer has deleted their account 422 buyer_account_deleted, as there is nobody to write to; a blocked thread 403 conversation_blocked.

POST

sellers

{sellerId}

orders

{orderId}

conversation

Message buyer about order

curl --request POST \
  --url https://{host}/v1/sellers/{sellerId}/orders/{orderId}/conversation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '
{
  "data": {
    "type": "conversations",
    "attributes": {
      "message": "When will my watch be shipped?"
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/vnd.api+json'},
  body: JSON.stringify({
    data: {type: 'conversations', attributes: {message: 'When will my watch be shipped?'}}
  })
};

fetch('https://{host}/v1/sellers/{sellerId}/orders/{orderId}/conversation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/v1/sellers/{sellerId}/orders/{orderId}/conversation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'type' => 'conversations',
        'attributes' => [
                'message' => 'When will my watch be shipped?'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/vnd.api+json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://{host}/v1/sellers/{sellerId}/orders/{orderId}/conversation"

payload = { "data": {
        "type": "conversations",
        "attributes": { "message": "When will my watch be shipped?" }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/vnd.api+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "type": "conversations",
    "id": "3312",
    "attributes": {
      "side": "seller",
      "unread": true,
      "archived": false,
      "noReplyNeeded": false,
      "buyer": {
        "name": "Jens Urlbauer",
        "initials": "JU",
        "estimatedCountry": "DE"
      },
      "blocked": false,
      "blockedByYou": false,
      "purpose": "propose_price",
      "lastMessage": {
        "id": "88120",
        "excerpt": "Price proposal",
        "from": "seller",
        "mine": false,
        "createdAt": "2026-09-21T09:30:11+02:00",
        "removed": false,
        "priceProposal": {
          "amount": 1300000,
          "currency": "EUR",
          "from": "seller",
          "status": "pending",
          "open": true,
          "payable": true,
          "generatedBody": true
        }
      },
      "agreedPrice": 1300000,
      "order": null,
      "createdAt": "2026-09-20T10:00:00.000000Z",
      "updatedAt": "2026-09-21T07:30:11.000000Z"
    },
    "relationships": {
      "watch": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/watch"
        }
      },
      "seller": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/seller"
        }
      },
      "messages": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/messages"
        }
      }
    },
    "links": {
      "self": "https://api.wristler.eu/v1/conversations/3312"
    }
  }
}

{
  "data": {
    "type": "conversations",
    "id": "3312",
    "attributes": {
      "side": "seller",
      "unread": true,
      "archived": false,
      "noReplyNeeded": false,
      "buyer": {
        "name": "Jens Urlbauer",
        "initials": "JU",
        "estimatedCountry": "DE"
      },
      "blocked": false,
      "blockedByYou": false,
      "purpose": "propose_price",
      "lastMessage": {
        "id": "88120",
        "excerpt": "Price proposal",
        "from": "seller",
        "mine": false,
        "createdAt": "2026-09-21T09:30:11+02:00",
        "removed": false,
        "priceProposal": {
          "amount": 1300000,
          "currency": "EUR",
          "from": "seller",
          "status": "pending",
          "open": true,
          "payable": true,
          "generatedBody": true
        }
      },
      "agreedPrice": 1300000,
      "order": null,
      "createdAt": "2026-09-20T10:00:00.000000Z",
      "updatedAt": "2026-09-21T07:30:11.000000Z"
    },
    "relationships": {
      "watch": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/watch"
        }
      },
      "seller": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/seller"
        }
      },
      "messages": {
        "links": {
          "related": "https://api.wristler.eu/v1/conversations/3312/messages"
        }
      }
    },
    "links": {
      "self": "https://api.wristler.eu/v1/conversations/3312"
    }
  }
}

{
  "errors": [
    {
      "status": "404",
      "code": "watch_reserved",
      "title": "Not Found",
      "detail": "<string>",
      "meta": {},
      "source": {
        "pointer": "/data/attributes/reference",
        "parameter": "<string>"
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

{
  "errors": [
    {
      "status": "404",
      "code": "watch_reserved",
      "title": "Not Found",
      "detail": "<string>",
      "meta": {},
      "source": {
        "pointer": "/data/attributes/reference",
        "parameter": "<string>"
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

{
  "errors": [
    {
      "status": "404",
      "code": "watch_reserved",
      "title": "Not Found",
      "detail": "<string>",
      "meta": {},
      "source": {
        "pointer": "/data/attributes/reference",
        "parameter": "<string>"
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

Authorizations

Authorization

string

header

required

A bearer token obtained through one of the two flows below.

Headers

Idempotency-Key

string

Optional. A UUID per logical operation, not per attempt: a retry carrying the same key gets the first attempt's answer back, headers and all, rather than performing the write twice. Honoured for 24 hours.

A refusal is an answer. A 422 is remembered like any other, so sending a corrected body under the same key answers 422 idempotency_key_reuse rather than accepting the correction — the point of a key is that one key means one decision. Use a new key for a new attempt at the request, and keep the old one only for retrying the same bytes after a timeout.

A 5xx is the exception: nothing was decided, so the key is released and the same one may be retried.

Refusal	Status	`code`
The same key with a different body	`422`	`idempotency_key_reuse`
The first request with this key is still running	`409`	`idempotency_in_progress`
The key's record vanished between two requests: retry with a new key	`409`	`idempotency_conflict`
A key longer than 191 characters	`400`	`idempotency_key_invalid`

A replayed answer carries Idempotent-Replay: true.

Maximum string length: 191

Path Parameters

sellerId

string

required

orderId

string

required

Body

application/vnd.api+json

A document creating one resource. No id: we mint it, and sending one is refused with 403.

data

object

required

Show child attributes

Response

The thread was already there; the message is in it.

A JSON:API document holding one resource.

data

object

required

Show child attributes

included

object[]

Show child attributes

Authentication

Account

Sellers

Inventory

Orders

Messaging (Quick replies)

Messaging (Blocked buyers)

Content (Filter pages)

Content (Insights)

Content (Pages)

Content (FAQ)

Catalogue

Messaging

Uploads

Messaging (Reports)

Account (Notifications)

Account (Security)

Account (Favorites)

Account (Blocked businesses)

Account (Saved searches)

Account (Orders)

Account (Checkout)

Account (Addresses)

Account (Devices)

Message buyer about order

Authorizations

Headers

Path Parameters

Body

Response