Ventas de Polar

Cada venta (un pago único o la renovación de una suscripción) es una order de Polar. Polar es el Merchant of Record: cobra al comprador, calcula y liquida el impuesto, le manda el comprobante y te acredita la venta en tu saldo de Polar (ver Saldo).

El objeto Order

{
  "id": "66f1c1e2c8a4b0d1f2e3a4d1",
  "provider": "polar",
  "polarOrderId": "5ca7caa3-d059-49aa-85c0-a0dfbee9844e",
  "paymentLinkId": "66f1c1e2c8a4b0d1f2e3a4b5",
  "polarSubscriptionId": null,
  "polarCheckoutId": "8150f7d1-6404-48c2-8797-842e71a500ad",
  "reference": "ORD-1001",
  "metadata": { "utm_source": "instagram" },
  "status": "paid",
  "billingReason": "purchase",
  "currency": "usd",
  "subtotalCents": 2500,
  "taxCents": 0,
  "totalCents": 2500,
  "netCents": 2337,
  "refundedCents": 0,
  "refundableCents": 2500,
  "customerEmail": "cliente@ejemplo.com",
  "customerName": "Ana Pérez",
  "productName": "Curso de fotografía",
  "seats": null,
  "sandbox": false,
  "createdAt": "2026-10-24T07:55:33.971Z"
}

• totalCents es lo que pagó el comprador y taxCents, el impuesto que liquida Polar. netCents es el monto sin impuesto (después de descuentos): es lo que Polar acredita en tu saldo, y de ahí descuenta su comisión. Lo que te queda por cada venta lo ves en Movimientos del dashboard.
• subtotalCents es el precio antes de descuentos; si el precio tenía el impuesto incluido (compradores de la UE), el impuesto está adentro.
• refundableCents es lo que todavía se puede reembolsar (sin impuesto).
• status: paid, partially_refunded, refunded, pending o void.
• billingReason: purchase (pago único), subscription_create o subscription_cycle (renovación).
• reference es tu referencia para esa venta (p. ej. el id de tu orden), metadata tu metadata y polarCheckoutId el checkout de Polar que la generó. Ver abajo.

Identificar cada venta con tu referencia

Toda venta trae una referencia única en el campo reference, en sus webhooks (data.charge.reference) y en /events:

• Con el link público (https://www.vexorpay.com/p/a1b2c3d4e5): cada visita genera una referencia nueva (VXP- + 12 caracteres, p. ej. VXP-7KQ4M9TZ2HXA). Puedes compartir el mismo link con toda tu audiencia: cada compra sale con la suya, nunca dos ventas con la misma.
• Con tu propio id: agrega ?reference=<tu-id> al link (/p/a1b2c3d4e5?reference=ORD-1001) o manda reference en POST /api/v1/payment-links/{id}/checkout, y se usa la tuya en vez de la generada. El checkout por API sin reference también genera una, y la respuesta la devuelve en reference (junto con polarCheckoutId, que vuelve en la venta).
• El link también acepta utm_source, utm_medium, utm_campaign, utm_content y utm_term, que quedan en metadata.

En una suscripción, la referencia queda en la suscripción y cada renovación la hereda. Para buscar una venta por referencia: GET /api/v1/orders?reference=VXP-7KQ4M9TZ2HXA. La referencia admite hasta 200 caracteres. Las ventas anteriores al 2026-10-30 pagadas sin referencia tienen reference: null.

Listar ventas

GET /api/v1/orders

curl "https://api.vexorpay.com/api/v1/orders?status=paid" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Ver una venta

GET /api/v1/orders/{id}

Devuelve la venta o 404 order_not_found.

Reembolsar una venta

POST /api/v1/orders/{id}/refund

Reembolsa una venta paid o partially_refunded, total o parcialmente. El dinero sale de tu saldo de Polar y el impuesto se devuelve en proporción. Es irreversible. Soporta Idempotency-Key: un replay devuelve la venta sin volver a reembolsar.

curl -X POST https://api.vexorpay.com/api/v1/orders/66f1c1e2c8a4b0d1f2e3a4d1/refund \
  -H "Authorization: Bearer vxp_live_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-ORD-1001" \
  -d '{ "amount": 10, "reason": "customer_request" }'

Devuelve la venta actualizada (refundedCents, refundableCents y status).

Errores