Optional network services

Basic integration, ordinary likes, matches and chat do not require buying additional services. A platform can join and use the network without them. The network provides services to platforms for their users; it does not collect payment directly from people. Platforms set their own user-facing offers and prices.

All four services start at 0 RUB. Even a zero-price order requires confirmation and a separate spending credential, and creates an entitlement. This lets you test integration before nonzero pricing. TEST credits are not money and cannot be used for live checkout. Positive RUB payments are not supported in the current release.

Available services

One day is exactly 24 hours. Entitlements belong to a particular member, identified by your own external_id. Each new superlike consumes a unit from the first executed action; the safety ceiling of five per day is not a free allowance. Ordinary likes remain free. Matches do not expire with time, and their lifetime is not sold. Reports, blocks, erasure and leaving the network remain free.

Explicit enrollment preserves existing integrations

First check GET /v1/capabilities. commerce_enabled means the full services API is enabled, not that your platform is enrolled. commerce_live_zero_only indicates zero-only RUB checkout. commerce_pilot describes the separate TEST-only development pilot; it is false in production.

Existing live clients retain legacy superlike/rewind behavior until explicit enrollment. Implement orders, entitlements and durable action references first, then contact us. An administrator enrolls the live spending account and delivers a separate X-Commerce-Key privately. The dashboard does not yet issue this credential or place orders. Keep it and your ordinary API key on your backend only.

Receiving promoted profiles is free and needs no spending account. You do not have to enable all services.

Quote, confirm, entitlement

1. GET /v1/commerce/catalog: current SKUs, currency, unit prices, quantity bounds and fulfillment_ready. Live checkout uses RUB; test checkout uses TEST. Do not substitute one for the other.
2. POST /v1/commerce/quotes: quote for your member, valid for five minutes. Nothing is charged or activated yet.
3. POST /v1/commerce/orders: confirmation with the normal Bearer key and separate X-Commerce-Key. external_order_ref is your durable order identifier.
4. GET /v1/members/{external_id}/entitlements: granted rights; GET /v1/members/{external_id}/boost: boost state and remaining time.

# Backend only. Use the quote UUID returned by the first request.
curl -X POST 'https://api.pereval.dating/v1/commerce/quotes' \
  -H "Authorization: Bearer $PEREVAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"member":"user-123","sku":"boost","quantity":40}'

curl -X POST 'https://api.pereval.dating/v1/commerce/orders' \
  -H "Authorization: Bearer $PEREVAL_API_KEY" \
  -H "X-Commerce-Key: $PEREVAL_COMMERCE_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"quote_id":"<returned UUID>","external_order_ref":"boost-order-42"}'

After a lost response, retry the same external_order_ref and quote_id: the same order returns without another activation or extension. Reusing the reference with another quote conflicts. Do not create a fresh order while the previous result is unknown. The quote snapshots the price; a disabled service or expired quote cannot be committed.

GET /v1/commerce/balance returns TEST credits or a zero-only RUB balance, not a bank account or monetary funding facility. Zero-price orders retain authorization, grants, accounting and replay protection. There is no automatic funding or renewal.

Boost: activation, delivery and time

• A boost starts immediately after successful order confirmation, including a zero-price order. Neither audience size nor a first impression is a prerequisite.
• Another purchase extends the same active generation without increasing strength or resetting rotation history. A purchase after completion creates a new generation.
• Started boosts cannot be voluntarily cancelled or refunded. Hiding or deleting the profile does not stop time. Platforms handle their own user warnings and financial arrangements.
• If incognito is already enabled, a new boost fails before order execution: 409 boost_incompatible_with_incognito. Incognito can be enabled during an existing boost: privacy takes effect immediately while time keeps running.
• Filters, consent, blocks and moderation take precedence. There is no guarantee of views, likes, matches or results with an empty audience.

The receiving platform opts in:

PUT /v1/commerce/delivery
{ "format": "search", "enabled": true }

Supported formats are swipe and search; disable with {"format":"none","enabled":false}. A map-based platform may buy outgoing boosts for its users, but receiving promotion on a map is not supported yet. Do not call an ordinary map point a fulfilled boost.

Additional promotion occupies at most 20% of a stable API stream (positions 5, 10, 15, and so on), without duplicates. Missing eligible boost candidates fall back to organic profiles. The receiving platform preserves priority in its interface. This is neither an obligation to show ads nor proof that a person viewed a card.

Keep X-Feed-Request-Ref, parameters and next_cursor for one logical search. Retries/pages belong to that search; an explicit new search gets a new reference. Sessions last 15 minutes, up to 200 candidates; changing filters requires a new search. Materialized pages do not count twice, and eligibility is rechecked before responding. The daily feed allowance is shared with the ordinary feed.

No per-card impression callbacks are required. api_placements means additional API placements, not human views. A detected checkpoint gap greater than ten seconds conservatively pauses the shared promotion clock and resumes the same generation with preserved remaining time. This mechanism does not detect every partial outage or the failure of an individual platform. A small audience is not an outage.

Superlikes and rewind: action retries

After enrolling a spending account, send X-Action-Ref for REST super likes and rewinds. The MCP like tool also accepts the reference as the action_ref argument for a super like. If you send both the argument and the header, their values must match. Reuse the reference only when retrying with the same sender, recipient, action and message. Retries across REST and MCP consume the entitlement once and emit one event. Use REST to place orders and rewind decisions.

Superlike execution and entitlement consumption are atomic; failed effects roll back consumption. Its optional message is part of the superlike, not a separate message-before-match product. Rewind needs a currently valid day entitlement, with no commercial operation counter. It cannot undo a match or resurrect erased chat. An expired right yields 402 entitlement_required on a new rewind.

Incognito: expiry and privacy

PUT /v1/members/{external_id}/incognito with {"enabled":true} enables the mode with a valid right; false disables it free of charge. Buying days grants permission but does not turn the mode on. Subsequent day purchases append nonoverlapping intervals. Turning the mode off does not pause entitlement expiry.

Expiry does not automatically publish the profile: privacy stays enabled and new browsing is blocked until renewal or an explicit return to normal mode. Previous disclosures and existing matches cannot be retroactively removed from another platform’s cache. Ordinary hiding with consent.network:false is free and needs no incognito purchase.

Errors and events

Main responses: 402 entitlement_required, 403 commerce_forbidden, 409 commerce_conflict, 409 quote_expired, 409 boost_incompatible_with_incognito, 422 invalid_commerce_request, 503 commerce_unavailable, 503 live_payments_unavailable. TEST credit exhaustion uses 402 insufficient_test_credits. Resolve the cause instead of blindly replacing the order reference.

Boost emits boost.started, boost.extended, boost.paused, boost.resumed and boost.completed through the normal event queue. Apply ordinary webhook signatures and deduplication. Safely ignore unknown event types for compatibility. After restoring an old backup, reconcile newer orders and actions before reopening entitlement issuance; clearing/replaying outbox is not that reconciliation.

See the API reference for fields and examples. Take current prices from the catalog, not documentation text. The network does not require platforms to charge their users, and payment never authorizes fake profiles or harvesting the network database.