Create a purchase

POST

/v1/purchases

curl --request POST \
  --url https://app.mondochat.io/v1/purchases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "conversation_id": "0199d6a0-2000-7000-8000-000000000001", "item_id": "private-show" }'

Starts a purchase in a conversation. Send exactly one of item_id, offer_message_id or amount_minor (a custom amount, where commerce.custom_amount is on). Takes a session token and an Idempotency-Key header. The purchase is created pending and follows commerce.payment_mode. server_charge calls your charge callout: paid marks it paid, insufficient answers next as a redirect to topup_url or commerce.topup_url_template, failed marks it failed, and pending is checked again after 30 seconds, 2 minutes, 10 minutes and 1 hour. page_callback answers next as page_callback: the host page pays and your server confirms. checkout_url answers a redirect to commerce.checkout_url_template filled in, and your server confirms. See https://docs.mondochat.io/guides/commerce/.

Authorizations

• session

Parameters

Header Parameters

Idempotency-Key

Any of:

string

string

>= 1 characters <= 255 characters

null

null

Request Body^required

Media typeapplication/json

PurchaseCreate

A purchase to make.

object

amount_minor

Any of:

integer

integer

>= 1

null

null

conversation_id

required

Conversation Id

The conversation to buy in.

string format: uuid

item_id

Any of:

string

string

<= 128 characters

null

null

offer_message_id

Any of:

string

string format: uuid

null

null

Responses

200

Successful Response

Media typeapplication/json

PurchaseResult

A purchase and what to do next.

object

buyer_id

required

Buyer Id

The buyer’s id.

string format: uuid

conversation_id

required

Any of:

string

string format: uuid

null

null

created_at

required

Created At

When the purchase was created.

string format: date-time

currency

required

Currency

ISO 4217 currency of the price.

string

external_ref

Any of:

string

string

null

null

id

required

Id

The purchase’s id.

string format: uuid

item

required

PurchaseItem

The item that was bought.

object

description

Any of:

string

string

<= 2000 characters

null

null

id

Any of:

string

string

null

null

kind

Any of:

string

string

null

null

title

required

Title

The item’s name.

string

>= 1 characters <= 200 characters

mode

required

Mode

How it is paid: the app’s commerce.payment_mode, or external for a purchase recorded from your server.

string

Allowed values: server_charge page_callback checkout_url external

next

required

PurchaseNext

What the client does next.

object

type

required

Type

done needs nothing; page_callback asks the host page to pay and your server to confirm; redirect sends the buyer to url.

string

Allowed values: done page_callback redirect

url

Any of:

string

string

null

null

price_minor

required

Price Minor

The price in minor units.

integer

seller_id

required

Seller Id

The seller’s id.

string format: uuid

status

required

Status

pending until paid; insufficient when the balance was short.

string

Allowed values: pending paid insufficient failed cancelled

Example

{
  "buyer_id": "0199d6a0-1000-7000-8000-000000000002",
  "conversation_id": "0199d6a0-2000-7000-8000-000000000001",
  "created_at": "2026-11-01T09:30:00Z",
  "currency": "EUR",
  "external_ref": "order-1042",
  "id": "0199d6a0-7000-7000-8000-000000000001",
  "item": {
    "id": "private-show",
    "kind": "show",
    "title": "Private show"
  },
  "mode": "server_charge",
  "next": {
    "type": "done"
  },
  "price_minor": 1500,
  "seller_id": "0199d6a0-1000-7000-8000-000000000001",
  "status": "paid"
}

4XX

Problem

Media typeapplication/problem+json

An RFC 9457 problem: the body of every error answer.

object

code

required

The stable error code to branch on, such as policy_denied.

string

detail

What went wrong this time, when there is more to say.

string | null

errors

For validation, one entry per invalid field.

Array<object>

One invalid field.

object

loc

The path to the field.

array

msg

What is wrong with it.

string

instance

The path of the request.

string

reason

For policy_denied and limit_reached, the rule or limit that refused the request; for forbidden, a short cause such as you_blocked; for banned, temporary when the ban expires.

string

status

required

The HTTP status code.

integer

title

required

A short summary of the problem.

string

type

required

A URL that names the problem, https://app.mondochat.io/problems/<code>.

string

Example

{
  "code": "policy_denied",
  "detail": null,
  "instance": "/v1/conversations/0199d6a0-2000-7000-8000-000000000001",
  "reason": "pins",
  "status": 403,
  "title": "Policy denied",
  "type": "https://app.mondochat.io/problems/policy_denied"
}