Product Meter Bindings

Endpointhttps://api.kontorion.eu/v1

Bindings that attach meters to products and map them to pricing variables.

List a product's bindings

GET

https://api.kontorion.eu/v1

/products/{id}/meter-bindings

Returns every meter binding on the product with each binding's meter summary embedded. Unpaginated.

List a product's bindings › path Parameters

id

string · uuid · required

Product UUID

List a product's bindings › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List a product's bindings › Responses

array | null · required

object · required

GET/products/{id}/meter-bindings

curl --request GET \
  --url https://api.kontorion.eu/v1/products/:id/meter-bindings

shell

Example Responses

{
  "data": [
    {
      "created_at": "2024-08-25T15:00:00Z",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "meter": {
        "function": "function",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "name": "name",
        "unit_label": "unit_label"
      },
      "meter_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "overlay_filters": {
        "root": {
          "children": [
            null
          ],
          "field": "field",
          "op": "op",
          "value": {}
        }
      },
      "pricing_var_name": "pricing_var_name",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "role": "BILLABLE_QUANTITY",
      "updated_at": "2024-08-25T15:00:00Z",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a product-meter binding

POST

https://api.kontorion.eu/v1

/products/{id}/meter-bindings

Wires a meter to a product with a named pricing variable. At most one BILLABLE_QUANTITY binding per product.

Create a product-meter binding › path Parameters

id

string · uuid · required

Product UUID

Create a product-meter binding › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a product-meter binding › Request Body

meter_id

string · uuid

Meter to bind to the product.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

object

Additional filter tree AND-ed onto the meter's own filters for this product only.

pricing_var_name

string

Formula variable name to expose the meter result as (slug); required for BILLABLE_QUANTITY and PRICING_VAR, optional for INFORMATIONAL.

role

string · enum

How the pipeline consumes the result: BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL.

Enum values:

BILLABLE_QUANTITY

PRICING_VAR

INFORMATIONAL

Create a product-meter binding › Responses

Created

object · required

POST/products/{id}/meter-bindings

curl --request POST \
  --url https://api.kontorion.eu/v1/products/:id/meter-bindings \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "meter_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "overlay_filters": {
    "root": {
      "children": [
        null
      ],
      "field": "field",
      "op": "op",
      "value": {}
    }
  },
  "pricing_var_name": "pricing_var_name",
  "role": "BILLABLE_QUANTITY"
}
'

shell

Example Request Body

{
  "meter_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "overlay_filters": {
    "root": {
      "children": [
        null
      ],
      "field": "field",
      "op": "op",
      "value": {}
    }
  },
  "pricing_var_name": "pricing_var_name",
  "role": "BILLABLE_QUANTITY"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "meter": {
      "function": "function",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "key": "key",
      "name": "name",
      "unit_label": "unit_label"
    },
    "meter_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "overlay_filters": {
      "root": {
        "children": [
          null
        ],
        "field": "field",
        "op": "op",
        "value": {}
      }
    },
    "pricing_var_name": "pricing_var_name",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "role": "BILLABLE_QUANTITY",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Get a binding

GET

https://api.kontorion.eu/v1

/products/{id}/meter-bindings/{bindingId}

Returns one binding with its meter summary embedded. A binding that exists under a different product than the URL names responds 404.

Get a binding › path Parameters

id

string · uuid · required

Product UUID

bindingId

string · uuid · required

Binding UUID

Get a binding › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a binding › Responses

object · required

GET/products/{id}/meter-bindings/{bindingId}

curl --request GET \
  --url https://api.kontorion.eu/v1/products/:id/meter-bindings/:bindingId

shell

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "meter": {
      "function": "function",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "key": "key",
      "name": "name",
      "unit_label": "unit_label"
    },
    "meter_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "overlay_filters": {
      "root": {
        "children": [
          null
        ],
        "field": "field",
        "op": "op",
        "value": {}
      }
    },
    "pricing_var_name": "pricing_var_name",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "role": "BILLABLE_QUANTITY",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Delete a binding

DELETE

https://api.kontorion.eu/v1

/products/{id}/meter-bindings/{bindingId}

Deletes the binding. The URL's product must own it (otherwise 404); already-published product versions keep their snapshot, so the removal reaches billing at the product's next publish.

Delete a binding › path Parameters

id

string · uuid · required

Product UUID

bindingId

string · uuid · required

Binding UUID

Delete a binding › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a binding › Responses

No Content

No data returned

Update a binding

PATCH

https://api.kontorion.eu/v1

/products/{id}/meter-bindings/{bindingId}

Merge-patch update. Every editable binding field is versioned on the binding's version row, so changes reach billing at the product's next publish. The URL's product must own the binding (otherwise 404).

Update a binding › path Parameters

id

string · uuid · required

Product UUID

bindingId

string · uuid · required

Binding UUID

Update a binding › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a binding › Request Body

object

Replacement overlay filter tree; null leaves it unchanged.

pricing_var_name

string

New formula variable name; null leaves it unchanged.

role

string · enum

New binding role (BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL); null leaves it unchanged.

Enum values:

BILLABLE_QUANTITY

PRICING_VAR

INFORMATIONAL

Update a binding › Responses

object · required

PATCH/products/{id}/meter-bindings/{bindingId}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/products/:id/meter-bindings/:bindingId \
  --header 'Content-Type: application/json' \
  --data '
{
  "overlay_filters": {
    "root": {
      "children": [
        null
      ],
      "field": "field",
      "op": "op",
      "value": {}
    }
  },
  "pricing_var_name": "pricing_var_name",
  "role": "BILLABLE_QUANTITY"
}
'

shell

Example Request Body

{
  "overlay_filters": {
    "root": {
      "children": [
        null
      ],
      "field": "field",
      "op": "op",
      "value": {}
    }
  },
  "pricing_var_name": "pricing_var_name",
  "role": "BILLABLE_QUANTITY"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "meter": {
      "function": "function",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "key": "key",
      "name": "name",
      "unit_label": "unit_label"
    },
    "meter_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "overlay_filters": {
      "root": {
        "children": [
          null
        ],
        "field": "field",
        "op": "op",
        "value": {}
      }
    },
    "pricing_var_name": "pricing_var_name",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "role": "BILLABLE_QUANTITY",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Meters Payment Gateways

List a product's bindings

GET

https://api.kontorion.eu/v1

/products/{id}/meter-bindings

Returns every meter binding on the product with each binding's meter summary embedded. Unpaginated.

List a product's bindings › path Parameters

id

string · uuid · required

Product UUID

List a product's bindings › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List a product's bindings › Responses

array | null · required

object · required

Create a product-meter binding

POST

https://api.kontorion.eu/v1

/products/{id}/meter-bindings

Wires a meter to a product with a named pricing variable. At most one BILLABLE_QUANTITY binding per product.

Create a product-meter binding › path Parameters

id

string · uuid · required

Product UUID

Create a product-meter binding › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a product-meter binding › Request Body

meter_id

string · uuid

Meter to bind to the product.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

object

Additional filter tree AND-ed onto the meter's own filters for this product only.

pricing_var_name

string

Formula variable name to expose the meter result as (slug); required for BILLABLE_QUANTITY and PRICING_VAR, optional for INFORMATIONAL.

role

string · enum

How the pipeline consumes the result: BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL.

Enum values:

BILLABLE_QUANTITY

PRICING_VAR

INFORMATIONAL

Create a product-meter binding › Responses

Created

object · required

Get a binding

GET

https://api.kontorion.eu/v1

/products/{id}/meter-bindings/{bindingId}

Returns one binding with its meter summary embedded. A binding that exists under a different product than the URL names responds 404.

Get a binding › path Parameters

id

string · uuid · required

Product UUID

bindingId

string · uuid · required

Binding UUID

Get a binding › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a binding › Responses

object · required

Delete a binding

DELETE

https://api.kontorion.eu/v1

/products/{id}/meter-bindings/{bindingId}

Deletes the binding. The URL's product must own it (otherwise 404); already-published product versions keep their snapshot, so the removal reaches billing at the product's next publish.

Delete a binding › path Parameters

id

string · uuid · required

Product UUID

bindingId

string · uuid · required

Binding UUID

Delete a binding › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a binding › Responses

No Content

No data returned

Update a binding

PATCH

https://api.kontorion.eu/v1

/products/{id}/meter-bindings/{bindingId}

Update a binding › path Parameters

id

string · uuid · required

Product UUID

bindingId

string · uuid · required

Binding UUID

Update a binding › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a binding › Request Body

object

Replacement overlay filter tree; null leaves it unchanged.

pricing_var_name

string

New formula variable name; null leaves it unchanged.

role

string · enum

New binding role (BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL); null leaves it unchanged.

Enum values:

BILLABLE_QUANTITY

PRICING_VAR

INFORMATIONAL

Update a binding › Responses

object · required