Crear precio - OnePay Documentación

curl https://api.onepay.la/v1/prices \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "x-idempotency: idem_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "9f5d85a0-1111-7000-aaaa-000000000001",
    "currency": "COP",
    "unit_amount_in_cents": 7990000,
    "nickname": "Mensual",
    "lookup_key": "pro_monthly",
    "recurring": {
      "interval": "month",
      "interval_count": 1,
      "trial_period_days": 0
    }
  }'

const response = await fetch('https://api.onepay.la/v1/prices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'x-idempotency': 'idem_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    product: '9f5d85a0-1111-7000-aaaa-000000000001',
    currency: 'COP',
    unit_amount_in_cents: 7990000,
    nickname: 'Mensual',
    lookup_key: 'pro_monthly',
    recurring: {
      interval: 'month',
      interval_count: 1,
      trial_period_days: 0
    }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.onepay.la/v1/prices',
    headers={
        'Authorization': 'Bearer sk_test_xxx',
        'x-idempotency': 'idem_xxx'
    },
    json={
        'product': '9f5d85a0-1111-7000-aaaa-000000000001',
        'currency': 'COP',
        'unit_amount_in_cents': 7990000,
        'nickname': 'Mensual',
        'lookup_key': 'pro_monthly',
        'recurring': {
            'interval': 'month',
            'interval_count': 1,
            'trial_period_days': 0
        }
    }
)

data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/prices",
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_xxx",
        "x-idempotency: idem_xxx",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "product" => "9f5d85a0-1111-7000-aaaa-000000000001",
        "currency" => "COP",
        "unit_amount_in_cents" => 7990000,
        "nickname" => "Mensual",
        "lookup_key" => "pro_monthly",
        "recurring" => [
            "interval" => "month",
            "interval_count" => 1,
            "trial_period_days" => 0
        ]
    ])
]);

$data = json_decode(curl_exec($curl), true);
?>

{
  "id": "9f5d85a0-2222-7000-aaaa-000000000002",
  "object": "price",
  "product": "9f5d85a0-1111-7000-aaaa-000000000001",
  "active": true,
  "nickname": "Mensual",
  "lookup_key": "pro_monthly",
  "currency": "COP",
  "unit_amount_in_cents": 7990000,
  "type": "recurring",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "total_cycles": null,
    "trial_period_days": 0
  },
  "created_at": "2026-07-13T12:00:00.000000Z"
}

{
  "message": "El campo product es obligatorio. (y 2 errores más)",
  "code": 10001,
  "code_name": "validation_error",
  "errors": {
    "product": [
      "El campo product es obligatorio."
    ],
    "unit_amount_in_cents": [
      "El campo unit amount in cents es obligatorio."
    ],
    "recurring.interval": [
      "El intervalo seleccionado no es válido. Usa day o month."
    ]
  }
}

{
  "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
  "code": 10003,
  "code_name": "idempotency_error"
}

POST

prices

curl https://api.onepay.la/v1/prices \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "x-idempotency: idem_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "9f5d85a0-1111-7000-aaaa-000000000001",
    "currency": "COP",
    "unit_amount_in_cents": 7990000,
    "nickname": "Mensual",
    "lookup_key": "pro_monthly",
    "recurring": {
      "interval": "month",
      "interval_count": 1,
      "trial_period_days": 0
    }
  }'

const response = await fetch('https://api.onepay.la/v1/prices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'x-idempotency': 'idem_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    product: '9f5d85a0-1111-7000-aaaa-000000000001',
    currency: 'COP',
    unit_amount_in_cents: 7990000,
    nickname: 'Mensual',
    lookup_key: 'pro_monthly',
    recurring: {
      interval: 'month',
      interval_count: 1,
      trial_period_days: 0
    }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.onepay.la/v1/prices',
    headers={
        'Authorization': 'Bearer sk_test_xxx',
        'x-idempotency': 'idem_xxx'
    },
    json={
        'product': '9f5d85a0-1111-7000-aaaa-000000000001',
        'currency': 'COP',
        'unit_amount_in_cents': 7990000,
        'nickname': 'Mensual',
        'lookup_key': 'pro_monthly',
        'recurring': {
            'interval': 'month',
            'interval_count': 1,
            'trial_period_days': 0
        }
    }
)

data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/prices",
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_xxx",
        "x-idempotency: idem_xxx",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "product" => "9f5d85a0-1111-7000-aaaa-000000000001",
        "currency" => "COP",
        "unit_amount_in_cents" => 7990000,
        "nickname" => "Mensual",
        "lookup_key" => "pro_monthly",
        "recurring" => [
            "interval" => "month",
            "interval_count" => 1,
            "trial_period_days" => 0
        ]
    ])
]);

$data = json_decode(curl_exec($curl), true);
?>

{
  "id": "9f5d85a0-2222-7000-aaaa-000000000002",
  "object": "price",
  "product": "9f5d85a0-1111-7000-aaaa-000000000001",
  "active": true,
  "nickname": "Mensual",
  "lookup_key": "pro_monthly",
  "currency": "COP",
  "unit_amount_in_cents": 7990000,
  "type": "recurring",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "total_cycles": null,
    "trial_period_days": 0
  },
  "created_at": "2026-07-13T12:00:00.000000Z"
}

{
  "message": "El campo product es obligatorio. (y 2 errores más)",
  "code": 10001,
  "code_name": "validation_error",
  "errors": {
    "product": [
      "El campo product es obligatorio."
    ],
    "unit_amount_in_cents": [
      "El campo unit amount in cents es obligatorio."
    ],
    "recurring.interval": [
      "El intervalo seleccionado no es válido. Usa day o month."
    ]
  }
}

{
  "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
  "code": 10003,
  "code_name": "idempotency_error"
}

Crea un precio (price) asociado a un producto existente. El precio define cuánto y cada cuánto se cobra.

Los precios son inmutables: una vez creados no puedes cambiar el monto, la moneda ni la recurrencia. Para cambiar de precio, crea uno nuevo y archiva el anterior con Archivar precio. Usa lookup_key junto con transfer_lookup_key para mover la clave estable al precio de reemplazo sin tocar tu código.

Headers

x-idempotency

string

required

Token único para garantizar la idempotencia de la petición

Body

product

string

required

ID de un producto tuyo al que pertenecerá el precio.

currency

string

required

Moneda ISO del cobro. Máximo 3 caracteres.

unit_amount_in_cents

integer

required

Monto a cobrar, expresado en centavos. Respeta el mínimo por moneda.

recurring

object

required

Configuración de recurrencia del cobro.

Show recurring

recurring.interval

string

required

Unidad del ciclo: day o month. Los valores week y year aún no están soportados y devuelven 422.

recurring.interval_count

integer

default:"1"

Número de intervalos por ciclo. Rango permitido: 1 a 36.

recurring.total_cycles

integer

Número total de ciclos a cobrar. null deja la recurrencia indefinida.

recurring.trial_period_days

integer

default:"0"

Días de prueba antes del primer cobro.

nickname

string

Etiqueta interna del precio. Máximo 100 caracteres.

lookup_key

string

Clave estable para re-apuntar el precio vigente sin cambiar tu código. Máximo 100 caracteres.

transfer_lookup_key

boolean

default:"false"

Si el lookup_key ya existe en otro precio, lo transfiere de forma atómica a este nuevo precio.

set_as_default

boolean

default:"false"

Marca este precio como el precio por defecto de su producto.

curl https://api.onepay.la/v1/prices \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "x-idempotency: idem_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "9f5d85a0-1111-7000-aaaa-000000000001",
    "currency": "COP",
    "unit_amount_in_cents": 7990000,
    "nickname": "Mensual",
    "lookup_key": "pro_monthly",
    "recurring": {
      "interval": "month",
      "interval_count": 1,
      "trial_period_days": 0
    }
  }'

const response = await fetch('https://api.onepay.la/v1/prices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'x-idempotency': 'idem_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    product: '9f5d85a0-1111-7000-aaaa-000000000001',
    currency: 'COP',
    unit_amount_in_cents: 7990000,
    nickname: 'Mensual',
    lookup_key: 'pro_monthly',
    recurring: {
      interval: 'month',
      interval_count: 1,
      trial_period_days: 0
    }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.onepay.la/v1/prices',
    headers={
        'Authorization': 'Bearer sk_test_xxx',
        'x-idempotency': 'idem_xxx'
    },
    json={
        'product': '9f5d85a0-1111-7000-aaaa-000000000001',
        'currency': 'COP',
        'unit_amount_in_cents': 7990000,
        'nickname': 'Mensual',
        'lookup_key': 'pro_monthly',
        'recurring': {
            'interval': 'month',
            'interval_count': 1,
            'trial_period_days': 0
        }
    }
)

data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/prices",
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_xxx",
        "x-idempotency: idem_xxx",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "product" => "9f5d85a0-1111-7000-aaaa-000000000001",
        "currency" => "COP",
        "unit_amount_in_cents" => 7990000,
        "nickname" => "Mensual",
        "lookup_key" => "pro_monthly",
        "recurring" => [
            "interval" => "month",
            "interval_count" => 1,
            "trial_period_days" => 0
        ]
    ])
]);

$data = json_decode(curl_exec($curl), true);
?>

Response

string

Identificador único del precio (UUID).

object

string

Tipo de objeto, siempre price.

product

string

ID del producto padre al que pertenece el precio.

active

boolean

Indica si el precio está vigente. Un precio archivado es false.

nickname

string

Etiqueta interna del precio. Puede ser null.

lookup_key

string

Clave estable para re-apuntar el precio vigente. Puede ser null.

currency

string

Moneda ISO del cobro (por ejemplo COP).

unit_amount_in_cents

integer

Monto a cobrar, expresado en centavos.

type

string

Tipo de precio, siempre recurring.

recurring

object

Configuración de recurrencia del cobro.

Show recurring

interval

string

Unidad del ciclo: day o month.

interval_count

integer

Número de intervalos por ciclo.

total_cycles

integer

Número total de ciclos. null cuando es indefinido.

trial_period_days

integer

Días de prueba antes del primer cobro.

created_at

string

Fecha de creación en formato ISO 8601.

{
  "id": "9f5d85a0-2222-7000-aaaa-000000000002",
  "object": "price",
  "product": "9f5d85a0-1111-7000-aaaa-000000000001",
  "active": true,
  "nickname": "Mensual",
  "lookup_key": "pro_monthly",
  "currency": "COP",
  "unit_amount_in_cents": 7990000,
  "type": "recurring",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "total_cycles": null,
    "trial_period_days": 0
  },
  "created_at": "2026-07-13T12:00:00.000000Z"
}

{
  "message": "El campo product es obligatorio. (y 2 errores más)",
  "code": 10001,
  "code_name": "validation_error",
  "errors": {
    "product": [
      "El campo product es obligatorio."
    ],
    "unit_amount_in_cents": [
      "El campo unit amount in cents es obligatorio."
    ],
    "recurring.interval": [
      "El intervalo seleccionado no es válido. Usa day o month."
    ]
  }
}

{
  "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
  "code": 10003,
  "code_name": "idempotency_error"
}

Detalle del precio

Archivar precio

​Headers

​Body

​Response

Headers

Body

Response