Add/Update Suscripción

Usa esto cuando a un cliente se le deba cobrar el mismo monto de forma programada, como un servicio mensual.


The following endpoint can be used to add or update a Suscripción within the Hyfin application. When a Suscripción is added to Hyfin, a request will be automatically generated and the customer will be notified via text message, email or both, as described under Who gets notified below. After submitting their payment method, the customer will automatically be charged based on the frequency of the recurring payment.

If the customer is viewing the Suscripción on their device and it gets updated, a message will display letting the customer know the Suscripción has been updated and the new version of the Suscripción will automatically be displayed on the customers device.

Quién recibe notificaciones

Cada cliente está bajo un solo control de notificaciones, determinado a partir del sitio y del cliente. Nunca se almacena y no se puede establecer directamente.

  • Control por contacto : cada dirección de correo electrónico y número de teléfono de los contactos del cliente tiene su propia doNotContact marca, y esa marca es lo único que detiene los mensajes automáticos hacia ella. Este es el control para los clientes creados en la app, para todos los clientes de un sitio de QuickBooks que no asigna métodos de pago a notificaciones, y para las integraciones en la API v4.
  • Control por cliente : las notificationOptions del cliente (una opción para cada uno: correo electrónico, mensaje de texto y WhatsApp) deciden para cada dirección de cada contacto. Si falta una opción, se notifica. Este es el control para todos los clientes de un sitio de QuickBooks que asigna métodos de pago a notificaciones, y para los clientes cuya integración definió esas opciones en una versión anterior a la 4.0.

En la API v4:

  • Una escritura de cliente o suscripción que incluya notificationOptions se rechaza con un error 400 y el mensaje "notification_options is not accepted on API v4. Set do_not_contact on the contact emails and phone_numbers instead."
  • En una escritura de Orden de compra, notificationOptions está obsoleta y se rechazará en una versión futura. Todavía se aplica, exactamente como en la 3.1: se convierte en los destinatarios de la Orden de compra send.to , y la respuesta es exitosa con una entrada de warnings . Si se envía junto con send.to se rechaza con un error 400. Cambie a send.to ahora.
  • Una escritura de cliente en un sitio que no está conectado a QuickBooks pasa a ese cliente al control por contacto. Sus opciones de notificación se copian en doNotContact en cada dirección una sola vez, luego se eliminan, y los doNotContact valores de la solicitud se aplican después de eso.
  • En un sitio de QuickBooks con mapPaymentMethodsToNotifications activado, los métodos de pago de QuickBooks deciden las notificaciones de todos los clientes, por lo que una escritura de cliente que incluya doNotContact se rechaza con un error 400 que nombra esa configuración. Omita la marca, o pida al comerciante que desactive la configuración.
  • onHold: false en una escritura de Orden de compra no libera una Orden de compra retenida porque no llega a nadie. Agregue un destinatario para que se pueda enviar.
  • La lectura del cliente nunca devuelve notificationOptions .

Punto Final

The following endpoint can be used to add or update a Suscripción. You must replace the {base_url} and {site_id} variable with the site id that was provided when the site was created.

POST
{base_url}/api/v4/site/{site_id}/subscription/addUpdate

Solicitud
Campo
Tipo
Descripción
_id
String
El id que asignamos a esta suscripción. Omítelo al crear una suscripción y envíalo al actualizar una.
externalId
String
Tu propio id para esta suscripción, desde tu software. Envía de nuevo el mismo externalId para actualizar esta suscripción en lugar de agregar una nueva. Usamos este valor para hacer la coincidencia, pero no evitamos duplicados, así que manténgalo único dentro del sitio.
description
String
Una breve descripción de los productos/servicios en la suscripción utilizada en la solicitud de pago mostrada al cliente.
amount
Number
El monto a cobrar por cada período de facturación. Este es un número entero de centavos, por lo que 1035 significa $10.35.
frequency
String
La frecuencia de facturación. Bi-Weekly cobra cada 14 días y Quarterly cada 3 meses. Semi-Monthly cobra dos veces al mes, el día de inicio y el día del mes que está a 14 días de distancia: un inicio el día 1 cobra el 1 y el 15, y un inicio el día 20 cobra el 20 y el 6. Semi-Annually cobra cada 6 meses en el día de inicio. Una suscripción Monthly iniciada del 29 al 31 cobra el último día de un mes más corto y después se queda en ese día.
One of Daily, Weekly, Bi-Weekly, Semi-Monthly, Monthly, Quarterly, Semi-Annually, Yearly
frequencyUnits
Number
Número de unidades de frecuencia entre cada pago. Ej.: frequency = Yearly y frequencyUnits = 2 significa cada 2 años. Solo aplica para Daily, Weekly, Monthly y Yearly, y se ignora para las demás frecuencias.
customer
Una referencia al registro del cliente.
startDate
La fecha de inicio de la suscripción. Si se deja en blanco, se establecerá cuando el cliente confirme su método de pago. Una fecha sin hora. Si se envía una hora o zona horaria con ella, se descarta, no se convierte, por lo que la fecha permanece tal como se escribió. Format = YYYY-MM-DD
numberOfPayments
Number
El número de pagos a realizar. Si se deja en blanco, la suscripción continúa indefinidamente o hasta que se cierre manualmente.
webhookUrl
String
La URL a la que se envía una publicación cuando se realizan ciertas acciones en la suscripción. Se envía un webhook cuando un pago alcanza un nuevo estado, y cuando un mensaje de texto, correo electrónico o mensaje de WhatsApp se envía, se entrega, se lee, se retrasa o falla, o cuando el cliente hace clic en el enlace de pago.
attachmentRefs
Una lista de adjuntos.
send
A quién se envía Suscripción, por canal. Un canal que incluyas se usa tal como lo indiques, y una lista vacía ([]) desactiva ese canal. Un canal que omitas conserva los destinatarios que Suscripción ya tiene, o se llena con los contactos del cliente, según el control de notificaciones del cliente, cuando aún no tiene ninguno. En una creación, omite send para que los contactos del cliente decidan cada canal cuando se envíe Suscripción. En una actualización, omitirlo conserva los destinatarios ya elegidos. Una lectura devuelve send.to como null hasta que se hayan elegido destinatarios. billTo.emails y billTo.sms siguen siendo la anulación de quién recibe esos canales, pero nunca reactivan un canal que send desactivó. Cada orden de compra que genera la suscripción se envía a estos destinatarios, tal como estén cuando se genera esa orden de compra, por lo que un cambio se aplica a las órdenes de compra generadas después.
billToCustomer
El cliente que recibe y paga la orden de compra, cuando no es customer.
billTo
Reemplazos opcionales para la sección Facturar a de la orden de compra. Si se proporciona billToCustomer, este objeto se combinará con la información del cliente y se puede usar para reemplazar campos específicos. Si no se proporciona billToCustomer, los campos de este objeto se usarán como la información de Facturar a en la orden de compra.
soldTo
Opciones adicionales para la sección de Vendido a / Cliente de la orden de compra.
deleted
Boolean
Esta bandera representa si el registro ha sido eliminado y ya no está disponible para ser utilizado.
			
{
  "description": "Gold+ Plan",
  "amount": 3499,
  "frequency": "Monthly",
  "frequencyUnits": 1,
  "customer": {
    "externalId": "39772634",
    "primaryContact": {
      "firstName": "John",
      "lastName": "Doe",
      "mobilePhone": "111-222-3333",
      "email": "johndoe@abc.com"
    }
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}


		
Respuesta
Campo
Tipo
Descripción
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if success is true.
One of added, updated
_id
String
The id we assign to the record.
updatedAt
The date the record was last updated. Un momento en el tiempo en formato ISO 8601, con zona horaria. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
link
String
El enlace que el cliente usa para confirmar su método de pago de la suscripción.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https://site.url/KA39T1A45JL"
}


		

Ver también