Rate Cards & Billable Items

These endpoints let you read and manage how customers are priced: the billable items (your catalogue of services and charges) and the rate cards that apply per-customer pricing for a validity period.

All endpoints are under /api/v1 and require an OAuth2 access token with the appropriate scope.

Scopes

Scope	Allows
`billable_items:read`	View billable items
`billable_items:write`	Create and update billable items
`billable_items:delete`	Delete billable items
`rate_cards:read`	View rate cards and their lines
`rate_cards:write`	Create and update rate cards and lines
`rate_cards:delete`	Delete rate cards and lines

Billable Items

A billable item is a service or charge you can bill for — for example a handling fee or a per-line charge. Each item has a default price, a trigger that decides when a charge is created, a VAT rate, and payment settings.

Method	Endpoint	Description
GET	`/billable-items`	List billable items. Filter by `item_type`, `category`, `trigger_event`, `trigger_type`, `is_active`, or `search`.
GET	`/billable-items/{id}`	Get one billable item.
POST	`/billable-items`	Create a billable item.
PUT	`/billable-items/{id}`	Update a billable item.
DELETE	`/billable-items/{id}`	Delete a billable item. Fails if it is used by any rate card — deactivate it instead.

List Billable Items


GET /api/v1/billable-items

Query Parameters

Parameter	Type	Description
`item_type`	string	Filter by type: `purchase` or `revenue`
`category`	string	Filter by category
`trigger_event`	string	Filter by trigger event (e.g. `on_release`, `on_acceptance`)
`trigger_type`	string	Filter by trigger type (e.g. `per_declaration`, `per_line`)
`is_active`	boolean	Filter by active status
`search`	string	Search across code and name
`per_page`	integer	Results per page (default: 25, max: 100)


curl https://app.borderbolt.com/api/v1/billable-items \
  -H "Authorization: Bearer {token}"

Get Billable Item


GET /api/v1/billable-items/{id}


curl https://app.borderbolt.com/api/v1/billable-items/1 \
  -H "Authorization: Bearer {token}"

Create a Billable Item


POST /api/v1/billable-items

Request Body

Field	Required	Type	Description
`code`	Yes	string	Unique item code (max 50 chars)
`name`	Yes	string	Display name (max 255 chars)
`default_price`	Yes	number	Default unit price (min 0)
`trigger_type`	Yes	string	When the charge is calculated: `per_declaration`, `per_line`, `fixed`, or `manual`
`trigger_event`	Yes	string	At which point the charge is created: `on_acceptance`, `on_release`, `on_finalization`, or `manual`
`item_type`	Yes	string	`purchase` (cost) or `revenue` (charge to customer)
`vat_rate`	No	number	VAT percentage (default: 21)
`category`	No	string	Grouping category
`description`	No	string	Optional description
`is_active`	No	boolean	Whether the item is available for use (default: `true`)


curl -X POST https://app.borderbolt.com/api/v1/billable-items \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HANDLING",
    "name": "Handling Fee",
    "default_price": 12.50,
    "trigger_type": "per_declaration",
    "trigger_event": "on_release",
    "item_type": "revenue",
    "vat_rate": 21
  }'

Example Response


{
  "data": {
    "id": 1,
    "code": "HANDLING",
    "name": "Handling Fee",
    "default_price": 12.50,
    "trigger_type": "per_declaration",
    "trigger_event": "on_release",
    "item_type": "revenue",
    "vat_rate": 21.00,
    "is_active": true,
    "created_at": "2026-01-01T10:00:00.000000Z"
  },
  "message": "Billable item created successfully"
}

HTTP 201 is returned on success.

Update a Billable Item


PUT /api/v1/billable-items/{id}

All fields are optional; only the fields you provide are updated.


curl -X PUT https://app.borderbolt.com/api/v1/billable-items/1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "default_price": 15.00,
    "vat_rate": 21
  }'

Delete a Billable Item


DELETE /api/v1/billable-items/{id}

Deletion fails if the item is linked to any rate card. Set is_active to false to deactivate it without removing it.


curl -X DELETE https://app.borderbolt.com/api/v1/billable-items/1 \
  -H "Authorization: Bearer {token}"

Rate Cards

A rate card applies pricing to a single customer for a validity period. It holds invoicing settings (frequency, consolidation) and a set of lines, each linking a billable item with optional price, VAT, and frequency overrides.

Method	Endpoint	Description
GET	`/rate-cards`	List rate cards. Filter by `customer_code`, `is_active`, `currently_valid`, or `search`.
GET	`/rate-cards/{id}`	Get one rate card with its lines.
GET	`/rate-cards/active/{customerCode}`	Get the currently-valid rate card for a customer.
POST	`/rate-cards`	Create a rate card.
PUT	`/rate-cards/{id}`	Update a rate card.
DELETE	`/rate-cards/{id}`	Delete a rate card and its lines.
POST	`/rate-cards/{id}/duplicate`	Copy a rate card and its lines (the copy starts inactive).
POST	`/rate-cards/{id}/lines`	Add a billable item line.
PUT	`/rate-cards/{id}/lines/{lineId}`	Update a line.
DELETE	`/rate-cards/{id}/lines/{lineId}`	Remove a line.

List Rate Cards


GET /api/v1/rate-cards

Query Parameters

Parameter	Type	Description
`customer_code`	string	Filter by customer code
`is_active`	boolean	Filter by active status
`currently_valid`	boolean	Return only cards valid on today’s date
`search`	string	Search by name or customer code
`per_page`	integer	Results per page (default: 25, max: 100)


curl https://app.borderbolt.com/api/v1/rate-cards \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "customer_code=CUST001" \
  --data-urlencode "currently_valid=true"

Get Rate Card


GET /api/v1/rate-cards/{id}

Returns the rate card together with its lines.


curl https://app.borderbolt.com/api/v1/rate-cards/10 \
  -H "Authorization: Bearer {token}"

Get Active Rate Card for a Customer


GET /api/v1/rate-cards/active/{customerCode}

Returns the currently-valid rate card for the given customer code, or 404 if none exists.


curl https://app.borderbolt.com/api/v1/rate-cards/active/CUST001 \
  -H "Authorization: Bearer {token}"

Create a Rate Card


POST /api/v1/rate-cards

Request Body

Field	Required	Type	Description
`customer_code`	Yes	string	Customer code the card applies to
`name`	Yes	string	Descriptive name (max 255 chars)
`valid_from`	Yes	date	Start date (`YYYY-MM-DD`)
`valid_until`	No	date	End date (`YYYY-MM-DD`); leave blank for open-ended
`invoice_frequency`	Yes	string	`immediate`, `delayed`, `daily`, `weekly`, or `monthly`
`consolidation_mode`	Yes	string	`per_dossier` (one invoice per dossier) or `merged` (all lines on one invoice)
`currency`	No	string	ISO 4217 currency code (default: `EUR`)
`is_active`	No	boolean	Whether the card is active (default: `true`)
`notes`	No	string	Free-text notes


curl -X POST https://app.borderbolt.com/api/v1/rate-cards \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_code": "CUST001",
    "name": "Standard 2026",
    "valid_from": "2026-01-01",
    "invoice_frequency": "monthly",
    "consolidation_mode": "merged",
    "currency": "EUR"
  }'

Example Response


{
  "data": {
    "id": 10,
    "customer_code": "CUST001",
    "name": "Standard 2026",
    "valid_from": "2026-01-01",
    "valid_until": null,
    "invoice_frequency": "monthly",
    "consolidation_mode": "merged",
    "currency": "EUR",
    "is_active": true,
    "lines": [],
    "created_at": "2026-01-01T10:00:00.000000Z"
  },
  "message": "Rate card created successfully"
}

HTTP 201 is returned on success.

Update a Rate Card


PUT /api/v1/rate-cards/{id}

All fields are optional; only the fields you provide are updated.


curl -X PUT https://app.borderbolt.com/api/v1/rate-cards/10 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "valid_until": "2026-12-31",
    "notes": "Renewed for 2026"
  }'

Delete a Rate Card


DELETE /api/v1/rate-cards/{id}

Deletes the rate card and all its lines.


curl -X DELETE https://app.borderbolt.com/api/v1/rate-cards/10 \
  -H "Authorization: Bearer {token}"

Duplicate a Rate Card


POST /api/v1/rate-cards/{id}/duplicate

Creates a copy of the rate card and all its lines. The copy is set to inactive so you can review and adjust it before activating.


curl -X POST https://app.borderbolt.com/api/v1/rate-cards/10/duplicate \
  -H "Authorization: Bearer {token}"

Rate Card Lines

Add a Line


POST /api/v1/rate-cards/{id}/lines

Adds a billable item to the rate card. A line cannot be added twice for the same billable item.

Request Body

Field	Required	Type	Description
`billable_item_id`	Yes	integer	ID of the billable item to add
`unit_price`	No	number	Override the default price for this customer; leave blank to use the item default
`vat_rate_override`	No	number	Override the VAT rate for this customer
`invoice_frequency_override`	No	string	Override the card-level frequency: `immediate`, `delayed`, `daily`, `weekly`, or `monthly`


curl -X POST https://app.borderbolt.com/api/v1/rate-cards/10/lines \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "billable_item_id": 1,
    "unit_price": 30.00,
    "vat_rate_override": 9
  }'

Example Response


{
  "data": {
    "id": 55,
    "billable_item_id": 1,
    "billable_item_code": "HANDLING",
    "billable_item_name": "Handling Fee",
    "unit_price": 30.00,
    "vat_rate_override": 9.00,
    "invoice_frequency_override": null
  },
  "message": "Line added successfully"
}

HTTP 201 is returned on success.

Update a Line


PUT /api/v1/rate-cards/{id}/lines/{lineId}

All fields are optional; only the fields you provide are updated.


curl -X PUT https://app.borderbolt.com/api/v1/rate-cards/10/lines/55 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "unit_price": 35.00
  }'

Remove a Line


DELETE /api/v1/rate-cards/{id}/lines/{lineId}


curl -X DELETE https://app.borderbolt.com/api/v1/rate-cards/10/lines/55 \
  -H "Authorization: Bearer {token}"

Next Steps

Invoices API — Generate and manage invoices from billable items
Dossiers API — Manage dossiers and revenue lines
Customers API — Customer master data