Prices API

The Prices API allows you to create, manage, and configure pricing for your subscription plans. Prices define the cost structure and billing frequency for your plans, including complex pricing models with tiers, usage-based components, and multiple currencies.

Overview

Prices represent the billing configuration for subscription plans. Each price can have:

Currency: Different pricing for different currencies
Pricing Models: Support for various pricing structures (flat rate, tiered, usage-based)
Plan Association: Linked to specific subscription plans
Override Capability: Can override existing pricing configurations

Authentication

All API requests require authentication via merchant credentials.

Endpoints

Get All Prices

Get all prices for the authenticated merchant, or filter by plan ID.

GET /api/prices

Query Parameters

Parameter	Type	Required	Description
`planId`	string		Plan ID to filter prices (format: plan_*)

Response

{
  "prices": [
    {
      "id": "price_123",
      "planId": "plan_456",
      "merchantId": "merchant_789",
      "currency": "USD",
      "pricingData": {
        "type": "flat_rate",
        "amount": 2900,
        "interval": "month"
      },
      "isOverridePrice": false,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "deletedAt": null
    }
  ]
}

Get Price by ID

Get a specific price by its ID.

GET /api/prices/{priceId}

Parameters

Parameter	Type	Description
`priceId`	string	Price ID (format: price_*)

Response

{
  "price": {
    "id": "price_123",
    "planId": "plan_456",
    "merchantId": "merchant_789",
    "currency": "USD",
    "pricingData": {
      "type": "tiered",
      "tiers": [
        {
          "upTo": 100,
          "unitAmount": 1000
        },
        {
          "upTo": null,
          "unitAmount": 800
        }
      ]
    },
    "isOverridePrice": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "deletedAt": null
  }
}

Create Price

Create a new price configuration for a subscription plan.

POST /api/prices

Request Body

{
  "planId": "plan_456",
  "currency": "USD",
  "pricingData": {
    "type": "flat_rate",
    "amount": 2900,
    "interval": "month"
  },
  "isOverridePrice": false
}

Request Fields

Field	Type	Required	Description
`planId`	string	✓	Plan ID to associate price with (format: plan_*)
`currency`	string		Currency code (defaults to merchant default currency)
`pricingData`	object	✓	Pricing configuration object
`isOverridePrice`	boolean		Whether this price overrides existing pricing

Pricing Data Schema

The pricingData object supports various pricing models:

Flat Rate Pricing

{
  "type": "flat_rate",
  "amount": 2900,
  "interval": "month"
}

Tiered Pricing

{
  "type": "tiered",
  "tiers": [
    {
      "upTo": 100,
      "unitAmount": 1000
    },
    {
      "upTo": 1000,
      "unitAmount": 800
    },
    {
      "upTo": null,
      "unitAmount": 500
    }
  ]
}

Usage-Based Pricing

{
  "type": "usage_based",
  "unitAmount": 10,
  "billingScheme": "per_unit"
}

Response

{
  "price": {
    "id": "price_789",
    "planId": "plan_456",
    "merchantId": "merchant_789",
    "currency": "USD",
    "pricingData": {
      "type": "flat_rate",
      "amount": 2900,
      "interval": "month"
    },
    "isOverridePrice": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "deletedAt": null
  }
}

Delete Price

Soft delete a price configuration.

DELETE /api/prices/{priceId}

Parameters

Parameter	Type	Description
`priceId`	string	Price ID to delete

Response

{
  "success": true
}

Clone Price

Clone an existing price with optional modifications.

POST /api/prices/clone/{priceId}

Parameters

Parameter	Type	Description
`priceId`	string	Source price ID to clone

Request Body

{
  "planId": "plan_789",
  "currency": "EUR",
  "pricingData": {
    "type": "flat_rate",
    "amount": 3200,
    "interval": "month"
  },
  "isOverridePrice": true
}

Request Fields

All fields are optional. If not provided, the values from the source price will be used.

Field	Type	Description
`planId`	string	Target plan ID (format: plan_*)
`currency`	string	Currency for the cloned price
`pricingData`	object	Updated pricing configuration
`isOverridePrice`	boolean	Whether the cloned price should be an override

Response

{
  "price": {
    "id": "price_999",
    "planId": "plan_789",
    "merchantId": "merchant_789",
    "currency": "EUR",
    "pricingData": {
      "type": "flat_rate",
      "amount": 3200,
      "interval": "month"
    },
    "isOverridePrice": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "deletedAt": null
  }
}

Examples

Creating a Simple Monthly Price

curl -X POST /api/prices \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "plan_123",
    "currency": "USD",
    "pricingData": {
      "type": "flat_rate",
      "amount": 1999,
      "interval": "month"
    }
  }'

Creating a Tiered Pricing Model

curl -X POST /api/prices \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "plan_123",
    "currency": "USD",
    "pricingData": {
      "type": "tiered",
      "tiers": [
        {
          "upTo": 100,
          "unitAmount": 1000
        },
        {
          "upTo": 1000,
          "unitAmount": 800
        },
        {
          "upTo": null,
          "unitAmount": 500
        }
      ]
    }
  }'

Creating a Usage-Based Price

curl -X POST /api/prices \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "plan_123",
    "currency": "USD",
    "pricingData": {
      "type": "usage_based",
      "unitAmount": 10,
      "billingScheme": "per_unit"
    }
  }'

Cloning a Price to Another Plan

curl -X POST /api/prices/clone/price_123 \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "plan_456",
    "currency": "EUR",
    "pricingData": {
      "type": "flat_rate",
      "amount": 2500,
      "interval": "month"
    }
  }'

Getting All Prices for a Specific Plan

curl -X GET '/api/prices?planId=plan_123' \
  -H "Authorization: Bearer your_api_key"

Getting All Prices for a Merchant

curl -X GET '/api/prices' \
  -H "Authorization: Bearer your_api_key"

Error Responses

All endpoints may return these error responses:

400 Bad Request

{
  "error": "Empty planId provided. Provide a planId or remove the query parameter"
}

{
  "error": "Invalid pricing data configuration"
}

403 Forbidden

{
  "error": "Unauthorized access to price"
}

404 Not Found

{
  "error": "Plan not found. If you have multiple accounts, are you using the right API key?"
}

{
  "error": "Price not found or access denied"
}

{
  "error": "Source price not found or access denied"
}

{
  "error": "Target plan not found or access denied"
}

500 Internal Server Error

{
  "error": "Failed to create price"
}

{
  "error": "Failed to clone price"
}

Important Notes

Pricing Data Configuration

Flat Rate: Simple fixed pricing with a single amount and billing interval
Tiered: Progressive pricing where different usage tiers have different unit costs
Usage-Based: Pricing based on actual usage or consumption
Override Prices: Can be used to temporarily override existing pricing

Currency Handling

Prices are specified in cents (e.g., 2900 = $29.00)
Each price can have a different currency
Currency defaults to the merchant's default currency if not specified
Multiple prices can exist for the same plan in different currencies

Plan Association

Each price must be associated with a specific plan
Multiple prices can exist for the same plan (different currencies, pricing models)
Plans are validated to ensure they belong to the authenticated merchant

Soft Deletion

Prices are soft deleted (marked with deletedAt timestamp)
Deleted prices are excluded from all queries automatically
This maintains historical pricing data while removing active pricing

Price Cloning

Cloning creates a complete copy of an existing price
You can modify any aspect of the cloned price during creation
Useful for creating similar pricing across multiple plans or currencies
The source price remains unchanged

Override Prices

Override prices can temporarily replace existing pricing configurations
Useful for promotional pricing, A/B testing, or special offers
Set isOverridePrice: true when creating override pricing

Prices API

On this page