Update or create a product item (upsert)

PUT

/v:version/product-items

PUT

/v:version/product-items

curl -X PUT https://test.api.solvimon.com/v1/product-items \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "product_id": "prod_fwDeeN0vxxHxTMCoh019",
  "name": "Enterprise platform fee",
  "reference": "enterprise_platform_fee",
  "model_type": "RECURRING",
  "description": "Monthly fee for dedicated capacity, SSO and a 99.9% uptime SLA",
  "type": "REVENUE",
  "tax_category": "STANDARD"
}'

{
  "object_type": "string",
  "id": "string",
  "product_id": "string",
  "product": {
    "object_type": "string",
    "id": "string",
    "category_id": "string",
    "category": {
      "object_type": "string",
      "id": "string",
      "name": "string",
      "reference": "string",
      "description": "string",
      "tax_category": "STANDARD",
      "display_order": 1,
      "customer_id": "string"
    },
    "parent_product_id": "string",
    "name": "string",
    "reference": "string",
    "description": "string",
    "status": "DRAFT",
    "product_type": "DEFAULT",
    "tax_category": "STANDARD",
    "features": [
      {
        "id": "string",
        "reference": "string"
      }
    ],
    "custom_fields": [
      {
        "id": "string",
        "reference": "string",
        "value": "string",
        "values": [
          "string"
        ],
        "integration_details": {
          "id": "string",
          "reference": "string",
          "payment_gateway_variant": "ADYEN",
          "adyen": {
            "recurring_detail_reference": "string"
          },
          "stripe": {
            "payment_method_id": "string"
          }
        },
        "integration_id": "string"
      }
    ],
    "display_order": 1,
    "linked_integrations": [
      {
        "id": "string",
        "link_details": [
          {
            "url": "string",
            "custom_field_name": "string"
          }
        ]
      }
    ],
    "billing_entity_id": "string",
    "customer_id": "string",
    "agent_context": {
      "guidance": "string"
    }
  },
  "name": "string",
  "status": "DRAFT",
  "reference": "string",
  "description": "string",
  "type": "REVENUE",
  "model_type": "USAGE_BASED",
  "usage_based": {
    "meter_value_calculation_id": "string",
    "meter_value_calculation": {
      "object_type": "string",
      "id": "string",
      "reference": "string",
      "name": "string",
      "description": "string",
      "calculation_type": "SUM",
      "persist": true,
      "meter_id": "string",
      "meter": {
        "object_type": "string",
        "id": "string",
        "reference": "string",
        "name": "string",
        "description": "string",
        "status": "DRAFT",
        "meter_values": [
          {
            "id": "string",
            "object": {
              "object_type": "string",
              "id": "string",
              "reference": "string",
              "name": "string",
              "description": "string",
              "status": "DRAFT",
              "type": "NUMBER"
            },
            "required": true
          }
        ],
        "meter_properties": [
          {
            "id": "string",
            "object": {
              "object_type": "string",
              "id": "string",
              "reference": "string",
              "name": "string",
              "description": "string",
              "status": "DRAFT",
              "type": "NUMBER",
              "enum_values": [
                "string"
              ]
            },
            "required": true
          }
        ]
      },
      "meter_value_id": "string",
      "meter_value": {
        "object_type": "string",
        "id": "string",
        "reference": "string",
        "name": "string",
        "description": "string",
        "status": "DRAFT",
        "type": "NUMBER"
      },
      "meter_property_id": "string",
      "meter_property": {
        "object_type": "string",
        "id": "string",
        "reference": "string",
        "name": "string",
        "description": "string",
        "status": "DRAFT",
        "type": "NUMBER",
        "enum_values": [
          "string"
        ]
      }
    },
    "tiering_meter_value_calculation_id": "string",
    "tiering_meter_value_calculation": {
      "object_type": "string",
      "id": "string",
      "reference": "string",
      "name": "string",
      "description": "string",
      "calculation_type": "SUM",
      "persist": true,
      "meter_id": "string",
      "meter": {
        "object_type": "string",
        "id": "string",
        "reference": "string",
        "name": "string",
        "description": "string",
        "status": "DRAFT",
        "meter_values": [
          {
            "id": "string",
            "object": {
              "object_type": "string",
              "id": "string",
              "reference": "string",
              "name": "string",
              "description": "string",
              "status": "DRAFT",
              "type": "NUMBER"
            },
            "required": true
          }
        ],
        "meter_properties": [
          {
            "id": "string",
            "object": {
              "object_type": "string",
              "id": "string",
              "reference": "string",
              "name": "string",
              "description": "string",
              "status": "DRAFT",
              "type": "NUMBER",
              "enum_values": [
                "string"
              ]
            },
            "required": true
          }
        ]
      },
      "meter_value_id": "string",
      "meter_value": {
        "object_type": "string",
        "id": "string",
        "reference": "string",
        "name": "string",
        "description": "string",
        "status": "DRAFT",
        "type": "NUMBER"
      },
      "meter_property_id": "string",
      "meter_property": {
        "object_type": "string",
        "id": "string",
        "reference": "string",
        "name": "string",
        "description": "string",
        "status": "DRAFT",
        "type": "NUMBER",
        "enum_values": [
          "string"
        ]
      }
    },
    "report_meter_value_calculation_ids": [
      "string"
    ],
    "conditions": {
      "name": "string",
      "expression": {
        "operator": "AND",
        "operands": [
          {
            "meter_property": {
              "id": "string",
              "reference": "string",
              "meter_property": {
                "object_type": "string",
                "id": "string",
                "reference": "string",
                "name": "string",
                "description": "string",
                "status": "DRAFT",
                "type": "NUMBER",
                "enum_values": [
                  "string"
                ]
              },
              "value": "string",
              "values": [
                "string"
              ],
              "meter_property_variable_id": "string",
              "meter_property_variable": {
                "object_type": "string",
                "id": "string",
                "reference": "string",
                "name": "string",
                "description": "string",
                "meter_property_id": "string",
                "type": "LIST",
                "status": "DRAFT",
                "value_count": 1,
                "created_at": "string",
                "updated_at": "string"
              },
              "comparator": "EQUALS"
            },
            "expression": {}
          }
        ]
      },
      "meter_properties": [
        {
          "id": "string",
          "reference": "string",
          "meter_property": {
            "object_type": "string",
            "id": "string",
            "reference": "string",
            "name": "string",
            "description": "string",
            "status": "DRAFT",
            "type": "NUMBER",
            "enum_values": [
              "string"
            ]
          },
          "value": "string",
          "values": [
            "string"
          ],
          "meter_property_variable_id": "string",
          "meter_property_variable": {
            "object_type": "string",
            "id": "string",
            "reference": "string",
            "name": "string",
            "description": "string",
            "meter_property_id": "string",
            "type": "LIST",
            "status": "DRAFT",
            "value_count": 1,
            "created_at": "string",
            "updated_at": "string"
          },
          "comparator": "EQUALS"
        }
      ]
    }
  },
  "credits": {
    "credit_type_id": "string",
    "credit_type": {
      "object_type": "string",
      "id": "string",
      "reference": "string",
      "status": "DRAFT",
      "name": "string",
      "description": "string",
      "unit_name": {
        "singular": "string",
        "plural": "string"
      },
      "created_at": "string",
      "updated_at": "string"
    }
  },
  "meter_value_calculation": {
    "object_type": "string",
    "id": "string",
    "reference": "string",
    "name": "string",
    "description": "string",
    "calculation_type": "SUM",
    "persist": true,
    "meter_id": "string",
    "meter": {
      "object_type": "string",
      "id": "string",
      "reference": "string",
      "name": "string",
      "description": "string",
      "status": "DRAFT",
      "meter_values": [
        {
          "id": "string",
          "object": {
            "object_type": "string",
            "id": "string",
            "reference": "string",
            "name": "string",
            "description": "string",
            "status": "DRAFT",
            "type": "NUMBER"
          },
          "required": true
        }
      ],
      "meter_properties": [
        {
          "id": "string",
          "object": {
            "object_type": "string",
            "id": "string",
            "reference": "string",
            "name": "string",
            "description": "string",
            "status": "DRAFT",
            "type": "NUMBER",
            "enum_values": [
              "string"
            ]
          },
          "required": true
        }
      ]
    },
    "meter_value_id": "string",
    "meter_value": {
      "object_type": "string",
      "id": "string",
      "reference": "string",
      "name": "string",
      "description": "string",
      "status": "DRAFT",
      "type": "NUMBER"
    },
    "meter_property_id": "string",
    "meter_property": {
      "object_type": "string",
      "id": "string",
      "reference": "string",
      "name": "string",
      "description": "string",
      "status": "DRAFT",
      "type": "NUMBER",
      "enum_values": [
        "string"
      ]
    }
  },
  "tax_category": "STANDARD",
  "display_order": 1,
  "unit_name": {
    "singular": "string",
    "plural": "string"
  },
  "custom_fields": [
    {
      "id": "string",
      "reference": "string",
      "value": "string",
      "values": [
        "string"
      ],
      "integration_details": {
        "id": "string",
        "reference": "string",
        "payment_gateway_variant": "ADYEN",
        "adyen": {
          "recurring_detail_reference": "string"
        },
        "stripe": {
          "payment_method_id": "string"
        }
      },
      "integration_id": "string"
    }
  ],
  "customer_id": "string",
  "agent_context": {
    "guidance": "string"
  },
  "meter_value_calculation_id": "string",
  "report_meter_value_calculation_ids": [
    "string"
  ]
}

Requires the PRODUCT_ITEM.CREATE or PRODUCT_ITEM.UPDATE permission.

Authentication

X-API-KEYstring

API Key authentication via header

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

versionstringRequiredDefaults to 1

version

Query parameters

identifier_fieldstringOptional

Which field to use to identify whether the resource exists or not

custom_field_referencestringOptional

Which custom field to use to identify whether the resource exists or not

field_actionsmap from strings to stringsOptional

The list of actions for specific fields.

Request

This endpoint expects an object.

product_idstring or nullRequired

The resource ID of the product, that belongs to the product item.

namestring or nullRequiredformat: "^.*$"0-256 characters

referencestringRequiredformat: "^\S+$"0-256 characters

model_typeenum or nullRequired

productobject or nullOptional

descriptionstring or nullOptionalformat: "^.*$"0-256 characters

typeenum or nullOptional

The type of the product item.

Allowed values:

usage_basedobjectOptional

Additional settings in case of a USAGE_BASED type.

creditsobjectOptional

Additional settings in case of a CREDITS type.

meter_value_calculationobject or nullOptional

tax_categoryenum or nullOptional

The default tax category applied to the product item.

Allowed values:

display_orderinteger or nullOptional

unit_nameobjectOptional

custom_fieldslist of objects or nullOptional

Custom fields associated to this product item

agent_contextobjectOptional

Context for AI agents about this product item. Intended for agents, not for customer-facing output.

meter_value_calculation_idstring or nullOptionalDeprecated

The linked meter value calculation, in case of a USAGE_BASED charge type.

report_meter_value_calculation_idslist of strings or nullOptionalDeprecated

Optional reporting meter value calculations, in case of a USAGE_BASED charge type.

Response

Created

object_typestring or nullOptionalRead-only

idstring or nullOptionalRead-only

product_idstring or nullOptional

The resource ID of the product, that belongs to the product item.

productobject or nullOptional

namestring or nullOptionalformat: "^.*$"0-256 characters

statusenum or nullOptionalRead-only

Allowed values:

referencestringOptionalformat: "^\S+$"0-256 characters

descriptionstring or nullOptionalformat: "^.*$"0-256 characters

typeenum or nullOptional

The type of the product item.

Allowed values:

model_typeenum or nullOptional

usage_basedobjectOptional

Additional settings in case of a USAGE_BASED type.

creditsobjectOptional

Additional settings in case of a CREDITS type.

meter_value_calculationobject or nullOptional

tax_categoryenum or nullOptional

The default tax category applied to the product item.

Allowed values:

display_orderinteger or nullOptional

unit_nameobjectOptional

custom_fieldslist of objects or nullOptional

Custom fields associated to this product item

customer_idstring or nullOptionalRead-only

agent_contextobjectOptional

Context for AI agents about this product item. Intended for agents, not for customer-facing output.

meter_value_calculation_idstring or nullOptionalDeprecated

The linked meter value calculation, in case of a USAGE_BASED charge type.

report_meter_value_calculation_idslist of strings or nullOptionalDeprecated

Optional reporting meter value calculations, in case of a USAGE_BASED charge type.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error

Authentication

Path parameters

Headers

Query parameters

Request

Response

Errors