Última modificación: 22 de agosto de 2025

Run in Postman

 En HubSpot, los elementos de pedido son instancias individuales de los productos. Cuando un producto está adjunto a un negocio, se convierte en un elemento de pedido. Puedes crear elementos de pedido únicos para una cotización individual, pero no se agregarán a tu biblioteca de productos. Los endpoints de elementos de pedido permiten gestionar estos datos y sincronizarlos entre HubSpot y otros sistemas. Ejemplo de uso: al crear un conjunto de cotizaciones para que los representantes de ventas las envíen a compradores potenciales, puedes usar esta API para crear elementos de pedido independientes por cotización, así como elementos de pedido que se adjuntan a productos existentes.

​
Permisos necesarios

Dependiendo de los endpoints que pienses utilizar, tendrás que autorizar los siguientes permisos:
  • crm.objects.line_items.read: proporciona acceso para recuperar datos de elementos de pedido.
  • crm.objects.line_items.write: proporciona acceso para crear y actualizar elementos de pedido.
  • tax_rates.read: proporciona acceso para recuperar los datos de las tasas de impuestos que hayas configurado en tu cuenta.

​
Crear un elemento de pedido

Para crear un elemento de pedido, haz una solicitud POST a /crm/v3/objects/line_items. En el cuerpo de la solicitud, incluye los detalles del elemento de pedido, como su nombre, la cantidad y el precio. También puedes incluir datos adicionales en el cuerpo de la solicitud:
  • Para crear un elemento de pedido basado en un producto existente (creado a través de la API de productos o n HubSpot), incluye hs_product_id en el cuerpo de la solicitud.
  • Para incluir la tasa de impuestos de tu elemento de pedido, incluye su ID como hs_tax_rate_group_id en el campo properties del cuerpo de la solicitud.
  • También puedes asociar el elemento de pedido con negocios, cotizaciones, facturas, enlaces de pago o suscripciones, incluyendo una matriz de associations en el cuerpo de la solicitud. Por ejemplo, el cuerpo de la siguiente solicitud crearía un elemento de pedido llamado “New standalone line item” (Nuevo elemento de pedido independiente) que está asociado con un negocio (ID: 12345).
{
  "properties": {
    "price": 10,
    "quantity": 1,
    "name": "New standalone line item",
    "hs_tax_rate_group_id": "2148420997"
  },
  "associations": [
    {
      "to": {
        "id": 12345
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 20
        }
      ]
    }
  ]
}

​
Nota:

  • Los elementos de pedido pertenecen a un único objeto principal. Si se asocian objetos, los elementos de pedido deben ser individuales para cada objeto. Por ejemplo, si estás creando un negocio y una cotización, debes crear un conjunto de elementos de pedido para el negocio y otro conjunto para la cotización. Esto ayudará a agilizar los datos del CRM en todos los objetos y evitará la pérdida inesperada de datos cuando se necesite modificar los elementos de pedido (por ejemplo, eliminar una cotización eliminará los elementos de pedido de la cotización, y si esos elementos de pedido están asociados con un negocio, los elementos de pedido de los negocios también se eliminarán).
  • El valor price especificado dentro del campo properties no puede ser negativo.
  • La propiedad Plazo de los elementos de pedido (hs_recurring_billing_period) acepta los formatos de período ISO-8601 de PnYnMnD y PnW.

​
Obtener un elemento de pedido

Puedes obtener elementos de pedido de forma individual o en bloque.
  • Para obtener un elemento de pedido específico, haz una solicitud GET a /crm/v3/objects/line_items/{lineItemId}, donde lineItemId es el ID del elemento de pedido.
  • Para obtener todos los elementos de pedido, haz una solicitud GET a /crm/v3/objects/line_items.
En la URL de la solicitud, puedes incluir los siguientes parámetros:
ParámetroDescripción
propertiesUna lista separada con comas de las propiedades que se devolverán en la respuesta. Si alguna de las propiedades especificadas no está presente en los objetos solicitados, se ignorará.
propertiesWithHistoryUna lista separada por comas de las propiedades que se devolverán junto con su historial de valores anteriores. Si alguna de las propiedades especificadas no está presente en los objetos solicitados, se ignorará.

​
Actualizar un elemento de pedido

Para actualizar un elemento de pedido, haz una solicitud PATCH a /crm/v3/objects/line_items/{lineItemId}, donde lineItemId es el ID del elemento de pedido. En el cuerpo de la solicitud, incluye los valores de propiedad que quieres actualizar. No puedes actualizar asociaciones con este método. En su lugar, deberás usar la API de asociaciones. Por ejemplo, el cuerpo de la solicitud puede tener un aspecto similar al siguiente: 
{
  "properties": {
    "price": 25,
    "quantity": 3,
    "name": "Updated line item"
  }
}

​
Eliminar un elemento de pedido

Para eliminar un elemento de pedido, haz una solicitud DELETE a /crm/v3/objects/line_items/{lineItemId}, donde lineItemId es el ID del elemento de pedido.

​
Propiedades de los elementos de pedido

Al gestionar los datos de los elementos de pedido, puede que quieras usar algunas de las propiedades comunes de esta tabla. Para obtener todas las propiedades de los elementos de pedido, haz una solicitud GET a /crm/v3/properties/line_item. Consulta más información sobre el uso de la API de propiedades.
Nombre de la propiedadEtiqueta en la interfaz de usuarioDescripción
nameNombreEl nombre del elemento de pedido.
descriptionDescripciónDescripción completa del producto
hs_skuSKUIdentificador único del producto
hs_recurring_billing_start_dateFecha de inicio de la facturaciónFacturación recurrente de un elemento de pedido
hs_recurring_billing_end_dateFecha de finalización de la facturaciónFacturación recurrente de un elemento de pedido
recurringbillingfrequencyFrecuencia de facturaciónCon qué frecuencia se factura un elemento de pedido con facturación periódica. Indica el cálculo de precios para negocios y cotizaciones. Los elementos de pedido con facturación única no están incluidos.
quantityCantidadCuántas unidades de un producto hay en este elemento de pedido
pricePrecio unitarioEl coste del producto
amountPrecio netoEl coste total del elemento de pedido (es decir, la cantidad multiplicada por el precio unitario).
hs_line_item_currency_codeDivisaCódigo de la divisa del elemento de pedido

​
Recuperar tasas de impuestos

Puedes aplicar una tasa de impuestos a elementos de pedido individuales (por ejemplo, un impuesto sobre las ventas de MA del 6,26%). Una vez que hayas configurado tu biblioteca de tasas de impuestos en tu cuenta de HubSpot, puedes hacer una solicitud GET a /tax-rates/v1/tax-rates para obtener todos las tasas de impuestos, o a /tax-rates/v1/tax-rates/{taxRateId} para obtener una tasa de impuestos por su ID. Tu aplicación tendrá que autorizar el permiso tax_rates.read para realizar esta solicitud. La respuesta tendrá el siguiente formato: 
{
  "name": "MA Sales tax 2025",
  "percentageRate": 6.25
  "label": "Sales Tax",
  "active": true,
  "id": "2148420997",
  "createdAt": "2024-12-12T23:20:39.923Z",
  "updatedAt": "2024-12-12T23:20:39.923Z"
}
Cada objeto de tasas de impuestos incluirá las siguientes propiedades:
Tipo de propiedadDescripción
nameEl descriptor interno de la tasa de impuestos.
percentageRateEl valor de la tasa de impuestos, expresado en porcentaje.
labelEl descriptor de la tasa de impuestos orientado al comprador, que se muestra en la cotización, factura u otros objetos padre.
activeUn booleano que indica si la tasa de impuestos puede aplicarse a una nueva cotización o factura. Puedes ajustarlo a false para una tasa de impuestos de un año anterior que ya no es aplicable.
idEl ID de la tasa de impuestos.
createdAtUna marca de tiempo ISO 8601 que indica cuándo se creó la tasa de impuestos.
updatedAtUna marca de tiempo ISO 8601 que indica cuándo se actualizó por última vez la tasa de impuestos.
Una vez que tengas el ID de la tasa de impuestos que quieres aplicar, proporciona ese id para el hs_tax_rate_group_id dentro del campo properties al crear un elemento de pedido. Más información sobre la creación de elementos de pedido en la sección anterior.