[eandreeva-twr]

Summary

The server-side API for virtual currency transactions now accepts seven optional fields that label a transaction: operation, feature, customer_placement_id, reference_id, is_sandbox, store, and store_transaction_id. The POST response and the transaction history return them. This PR documents them and corrects the reference where it didn't match the endpoints.

API reference (adapty-api.yaml)

• Create virtual currency transaction
  • Adds the seven request fields, with formats and the operation values.
  • Success is 201 Created, not 200. The response is now the full transaction (same shape as a history item) plus balances and response_created_at.
  • Request examples are labeled. A new example credits coins for a purchase the backend handles itself (store + store_transaction_id).
  • Error responses now match what the endpoint returns. All request validation is 400 validation_error, and the new error codes are parse_error and unknown_store. Removed: 403 feature_not_enabled, 422, 409 duplicate_source_transaction, and the amount_zero / empty_items / duplicate_currency codes.
• List virtual currency transactions: Adds the seven fields to the history item, labels the examples, and adds 400 validation_error. Removes 403.
• List virtual currency balances: 400 is validation_error (missing profile header). Removes 403.

Guides

• Virtual currencies: New Label transactions section. It covers why to label, the four common operation values, feature format with good and bad examples, the other fields, a warning about double-crediting linked products, and what happens to older transactions.
• Virtual currency quickstart: The spend example sets operation: spend and feature: image_generation.
• Grant an initial balance: The grant example uses operation: reward and feature: welcome instead of metadata.reason. The response example now shows the new shape.

Notes for review

• On history items, operation lists the values Adapty sets on its own transactions: top_up for store purchases, renewals, and trials, refund, expiry, and reward for dashboard_transaction. These follow the backend mapping on master.
• Not included: a release-notes entry and a "your metadata key → our field" mapping table.
• Localized specs and articles update through the translation workflow.

Verification

• check-mdx-parse and lint-mdx pass on the changed articles.
• API reference unit tests: 39 pass, 1 fail. The failure is the locale-loading test, and it also fails on main.