Prices

A price defines how much to charge for a product and how often. Every product can have multiple prices — for example a monthly plan and an annual plan for the same service, or regional prices in different currencies. When a line item on an invoice references a price (price_…), the unit amount, currency, and tax rate are automatically borrowed from the price. You can still override the description, quantity, and discount at the line-item level. All monetary amounts are integers in minor currency units. For USD, 5000 means $50.00. For JPY (a zero-decimal currency), 5000 means ¥5000. Base URL: https://invoice.horizonpay.co/api/v1

The price object

{
  "id": "price_01hxyz1234567890abcdefghij",
  "object": "price",
  "product": "prod_01hxyz1234567890abcdefghij",
  "nickname": "Monthly Pro",
  "unit_amount": 4900,
  "currency": "USD",
  "billing_scheme": "per_unit",
  "type": "recurring",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "tax_rate": 8.5,
  "active": true,
  "created": "2024-01-10T11:05:00.000Z"
}

string

Unique identifier for the price. Prefixed with price_.

string

String literal "price".

string

The prod_-prefixed ID of the parent product.

string | null

Optional internal label for the price (e.g. "Monthly Pro", "Enterprise Annual"). Not shown to customers.

integer

The unit price in minor currency units. 4900 USD = $49.00. Must be a non-negative integer.

string

Three-letter ISO 4217 currency code, uppercase (e.g. "USD", "EUR", "GBP").

string

Always "per_unit". Tiered and volume billing are not supported in the current API version.

string

"one_time" for a single charge, or "recurring" for a price that repeats on an interval.

object | null

Present when type is "recurring", null for "one_time" prices.

Show recurring fields

string

Billing interval. One of "day", "week", "month", or "year".

integer

Number of intervals between billings. interval: "month" and interval_count: 3 means every 3 months (quarterly). Minimum 1, maximum 52.

number

Tax rate percentage to apply to this price, e.g. 8.5 for 8.5%. Range: 0–100.

boolean

true while the price is available to attach to new invoice lines.

string

ISO 8601 datetime at which the price was created.

Endpoints

GET /api/v1/prices — List prices

List prices across your catalog. Results are cursor-paginated.Required scope: products:read

Query parameters

string

Filter to prices belonging to a specific product. Accepts a prod_-prefixed ID or UUID.

boolean

Pass true for active prices only, false for archived ones. Omit to return both.

string

Filter by three-letter currency code (e.g. USD).

string

Filter by price type. One of one_time or recurring.

string

Pagination cursor from a previous next_cursor. Omit to start from the first page.

integer

Results per page. Defaults to 20; maximum is 100.

Request

curl "https://invoice.horizonpay.co/api/v1/prices?product=prod_01hxyz1234567890abcdefghij&type=recurring" \
  -H "Authorization: Bearer inv_live_..."

Response

{
  "data": [
    {
      "id": "price_01hxyz1234567890abcdefghij",
      "object": "price",
      "product": "prod_01hxyz1234567890abcdefghij",
      "nickname": "Monthly Pro",
      "unit_amount": 4900,
      "currency": "USD",
      "billing_scheme": "per_unit",
      "type": "recurring",
      "recurring": {
        "interval": "month",
        "interval_count": 1
      },
      "tax_rate": 0,
      "active": true,
      "created": "2024-01-10T11:05:00.000Z"
    },
    {
      "id": "price_01hxyz9876543210zyxwvutsrq",
      "object": "price",
      "product": "prod_01hxyz1234567890abcdefghij",
      "nickname": "Annual Pro",
      "unit_amount": 47880,
      "currency": "USD",
      "billing_scheme": "per_unit",
      "type": "recurring",
      "recurring": {
        "interval": "year",
        "interval_count": 1
      },
      "tax_rate": 0,
      "active": true,
      "created": "2024-01-10T11:10:00.000Z"
    }
  ],
  "next_cursor": null
}

POST /api/v1/prices — Create a price

Create a new price and attach it to an existing product. For recurring prices, the recurring object is required.Required scope: products:write

unit_amount is always in minor units (integer). For a price of $49.00 USD, send 4900. For £120.00 GBP, send 12000.

Body parameters

string

required

The prod_-prefixed ID or UUID of the parent product.

integer

required

Price in minor currency units. Must be a non-negative integer.

string

required

Three-letter ISO 4217 currency code, uppercase (e.g. "USD").

string

"one_time" (default) or "recurring". When "recurring", the recurring object is required.

object

Required when type is "recurring".

Show recurring fields

string

required

Billing interval: "day", "week", "month", or "year".

integer

Number of intervals per billing cycle. Defaults to 1. Maximum 52.

number

Tax rate percentage, e.g. 8.5 for 8.5%. Range: 0–100. Defaults to 0.

string

Internal label for this price.

Request — one-time price

curl https://invoice.horizonpay.co/api/v1/prices \
  -X POST \
  -H "Authorization: Bearer inv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product": "prod_01hxyz1234567890abcdefghij",
    "unit_amount": 150000,
    "currency": "USD",
    "type": "one_time",
    "tax_rate": 8.5,
    "nickname": "Enterprise Setup Fee"
  }'

Response `201 Created`

{
  "data": {
    "id": "price_01hxyz1111222233334444aaaa",
    "object": "price",
    "product": "prod_01hxyz1234567890abcdefghij",
    "nickname": "Enterprise Setup Fee",
    "unit_amount": 150000,
    "currency": "USD",
    "billing_scheme": "per_unit",
    "type": "one_time",
    "recurring": null,
    "tax_rate": 8.5,
    "active": true,
    "created": "2024-06-01T09:00:00.000Z"
  }
}

Request — recurring price

curl https://invoice.horizonpay.co/api/v1/prices \
  -X POST \
  -H "Authorization: Bearer inv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product": "prod_01hxyz1234567890abcdefghij",
    "unit_amount": 4900,
    "currency": "USD",
    "type": "recurring",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "nickname": "Monthly Pro"
  }'

Response `201 Created`

{
  "data": {
    "id": "price_01hxyz1234567890abcdefghij",
    "object": "price",
    "product": "prod_01hxyz1234567890abcdefghij",
    "nickname": "Monthly Pro",
    "unit_amount": 4900,
    "currency": "USD",
    "billing_scheme": "per_unit",
    "type": "recurring",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "tax_rate": 0,
    "active": true,
    "created": "2024-06-01T09:05:00.000Z"
  }
}

GET /api/v1/prices/:id — Retrieve a price

Retrieve a single price by ID.Required scope: products:readThe :id path parameter accepts either the price_-prefixed public ID or the underlying UUID.

Request

curl https://invoice.horizonpay.co/api/v1/prices/price_01hxyz1234567890abcdefghij \
  -H "Authorization: Bearer inv_live_..."

Response `200 OK`

{
  "data": {
    "id": "price_01hxyz1234567890abcdefghij",
    "object": "price",
    "product": "prod_01hxyz1234567890abcdefghij",
    "nickname": "Monthly Pro",
    "unit_amount": 4900,
    "currency": "USD",
    "billing_scheme": "per_unit",
    "type": "recurring",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "tax_rate": 0,
    "active": true,
    "created": "2024-01-10T11:05:00.000Z"
  }
}

PATCH /api/v1/prices/:id — Update a price

Update mutable fields on a price. Omitted fields are left unchanged.Required scope: products:write

The parent product cannot be changed after creation. To move a price to a different product, create a new price and archive the old one.

unit_amount remains in minor units on update. To change a

49.00 price to

59.00, send "unit_amount": 5900.

Body parameters

All fields are optional.

string | null

New internal label. Pass null or "" to clear.

integer

New price in minor currency units.

string

New three-letter currency code.

string

"one_time" or "recurring". Changing type requires updating the recurring object accordingly.

object

Update the recurring interval. Only meaningful when type is "recurring".

Show recurring fields

string

Billing interval: "day", "week", "month", or "year".

integer

Number of intervals per cycle. Min 1, max 52.

number

New tax rate percentage. Range: 0–100.

boolean

Set to false to deactivate without deleting.

Request

curl https://invoice.horizonpay.co/api/v1/prices/price_01hxyz1234567890abcdefghij \
  -X PATCH \
  -H "Authorization: Bearer inv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "unit_amount": 5900,
    "nickname": "Monthly Pro (2024)"
  }'

Response `200 OK`

{
  "data": {
    "id": "price_01hxyz1234567890abcdefghij",
    "object": "price",
    "product": "prod_01hxyz1234567890abcdefghij",
    "nickname": "Monthly Pro (2024)",
    "unit_amount": 5900,
    "currency": "USD",
    "billing_scheme": "per_unit",
    "type": "recurring",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "tax_rate": 0,
    "active": true,
    "created": "2024-01-10T11:05:00.000Z"
  }
}

DELETE /api/v1/prices/:id — Archive a price

Archive a price. The price is set to active: false and will no longer be returned when filtering by active=true. Existing invoice lines that reference this price are not affected.Required scope: products:writeTo reactivate an archived price, use PATCH /api/v1/prices/:id with "active": true.

Request

curl https://invoice.horizonpay.co/api/v1/prices/price_01hxyz1234567890abcdefghij \
  -X DELETE \
  -H "Authorization: Bearer inv_live_..."

Response `200 OK`

The archived price object is returned, with active: false.

{
  "data": {
    "id": "price_01hxyz1234567890abcdefghij",
    "object": "price",
    "product": "prod_01hxyz1234567890abcdefghij",
    "nickname": "Monthly Pro",
    "unit_amount": 4900,
    "currency": "USD",
    "billing_scheme": "per_unit",
    "type": "recurring",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "tax_rate": 0,
    "active": false,
    "created": "2024-01-10T11:05:00.000Z"
  }
}

Error responses

Status	Cause
`400 Bad Request`	Missing `product`, `unit_amount`, or `currency`; non-integer `unit_amount`; missing `recurring` object when `type` is `"recurring"`; or invalid currency code.
`401 Unauthorized`	Missing or invalid `Authorization` header.
`403 Forbidden`	The API key lacks `products:read` or `products:write`.
`404 Not Found`	No price or product with the given ID exists in your workspace.

Overview

Invoices

Customers & Catalog

Webhooks

Prices API — List, Create, Retrieve, Update, Archive

Prices

The price object

Endpoints

Query parameters

Request

Response

Body parameters

Request — one-time price

Response `201 Created`

Request — recurring price

Response `201 Created`

Request

Response `200 OK`

Body parameters

Request

Response `200 OK`

Request

Response `200 OK`

Error responses

​Prices

​The price object

​Endpoints

​Query parameters

​Request

​Response

​Body parameters

​Request — one-time price

​Response 201 Created

​Request — recurring price

​Response 201 Created

​Request

​Response 200 OK

​Body parameters

​Request

​Response 200 OK

​Request

​Response 200 OK

​Error responses

Prices

The price object

Endpoints

Query parameters

Request

Response

Body parameters

Request — one-time price

Response `201 Created`

Request — recurring price

Response `201 Created`

Request

Response `200 OK`

Body parameters

Request

Response `200 OK`

Request

Response `200 OK`

Error responses