Products

Create and manage products. Products define the goods or services you offer, along with their pricing, billing interval, and phase schedules.

The Product object

Attributes
idstring

Unique identifier for the product

objectstring

Object type identifier. Always product.

namestring

Product name shown on invoices and receipts

descriptionnullable string

Optional product description

createdinteger

Unix timestamp of creation

updatedinteger

Unix timestamp of last update

livemodeboolean

true if live mode, false if test mode

activeboolean

true if the product is available for purchase

metadataobject

Set of key-value pairs for your own reference

THE PRODUCT OBJECT
{
  "id": "d5e6f7g8-2345-6789-bcde-0f1a2b3c4d5e",
  "object": "product",
  "name": "Platform Plus",
  "description": "Full-featured platform plan with priority support",
  "created": 1721010605,
  "updated": 1721010605,
  "livemode": false,
  "active": true,
  "metadata": {}
}

List products

Returns a list of your products. The products are returned sorted by creation date, with the most recently created products appearing first.

A dictionary with a data property that contains an array of up to limit products is returned. Each entry in the array is a separate product object. If no more products are available, the resulting array will be empty.

Query parameters
pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Returns

A paginated list of product objects

GET/v1/products
curl --request GET \
  --url https://api.framepayments.com/v1/products \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/products",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "fee2a365-e365-4393-b2b5-f4c5a4df69b9",
      "name": "Synergistic Cotton Bench",
      "description": "quam",
      "url": "https://google.com",
      "shippable": true,
      "purchase_type": "one_time",
      "recurring": null,
      "object": "product",
      "active": true,
      "default_price": 10000,
      "created": 1781115884,
      "updated": 1781115884,
      "livemode": false,
      "image": null,
      "metadata": {}
    },
    {
      "id": "a1fda643-581a-4bf6-8874-1e8ca93c13ec",
      "name": "Lightweight Copper Hat",
      "description": "minus",
      "url": "https://google.com",
      "shippable": true,
      "purchase_type": "one_time",
      "recurring": null,
      "object": "product",
      "active": true,
      "default_price": 10000,
      "created": 1781115884,
      "updated": 1781115884,
      "livemode": false,
      "image": null,
      "metadata": {}
    },
    {
      "id": "967e3314-5052-471a-8e4c-82cfac0f11c5",
      "name": "Small Granite Shoes",
      "description": "qui",
      "url": "https://google.com",
      "shippable": true,
      "purchase_type": "one_time",
      "recurring": null,
      "object": "product",
      "active": true,
      "default_price": 10000,
      "created": 1781115884,
      "updated": 1781115884,
      "livemode": false,
      "image": null,
      "metadata": {}
    }
  ]
}

Create product

Creates a new product object.

Returns a product object if the call succeeded.

Body parameters
namestringrequired

The product's name, meant to be displayable to the customer.

descriptionstringoptional

The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.

default_priceintegeroptional

The default price for this product in cents.

purchase_typeenumoptional

Specifies product type. Either one_time or recurring.

shippablebooleanoptional

Whether this product is shipped (i.e., physical goods).

urlstringoptional

A URL of a publicly-accessible webpage for this product.

recurring_intervalenumoptional

Specifies billing frequency. Either daily, monthly, weekly, yearly, every_3_months, or every_6_months. Required if purchase_type is recurring.

billing_creditsintegeroptional

Billing credits for the product

metadataobjectoptional

Additional custom metadata for the product

Returns

Returns a product object if the call succeeded

POST/v1/products
curl --request POST \
  --url https://api.framepayments.com/v1/products \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": null
}'
RESPONSE
{
  "id": "b80160f7-2adc-4e31-8f13-39d5b0a7b763",
  "name": "Test Product",
  "description": "A test product",
  "url": null,
  "shippable": false,
  "purchase_type": "one_time",
  "recurring": null,
  "object": "product",
  "active": true,
  "default_price": 2999,
  "created": 1781115884,
  "updated": 1781115884,
  "livemode": false,
  "image": null,
  "metadata": {}
}

Get product

Retrieves the details of an existing product. Supply the unique product ID from either a product creation request or the product list, and Frame will return the corresponding product information.

Returns a product object if a valid identifier was provided.

Path parameters
idstringrequired

Unique identifier for the product.

Returns

Returns a product object if a valid identifier was provided

GET/v1/products/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "4a321d27-a9e3-436d-a9b8-a11ffd075a05",
  "name": "Rustic Rubber Table",
  "description": "aspernatur",
  "url": "https://google.com",
  "shippable": true,
  "purchase_type": "one_time",
  "recurring": null,
  "object": "product",
  "active": true,
  "default_price": 10000,
  "created": 1781115884,
  "updated": 1781115884,
  "livemode": false,
  "image": null,
  "metadata": {}
}

Update product

Updates the specific product by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Returns the product object if the update succeeded.

Path parameters
idstringrequired

Unique identifier for the product.

Query parameters
namestringoptional

The product's name, meant to be displayable to the customer.

descriptionstringoptional

The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.

default_priceintegeroptional

The default price for this product in cents.

purchase_typeenumoptional

Specifies product type. Either one_time or recurring.

shippablebooleanoptional

Whether this product is shipped (i.e., physical goods).

urlstringoptional

A URL of a publicly-accessible webpage for this product.

recurring_intervalenumoptional

Specifies billing frequency. Either daily, monthly, weekly, yearly, every_3_months, or every_6_months.

billing_creditsintegeroptional

Billing credits for the product

Returns

Returns the product object if the update succeeded

PATCH/v1/products/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "79af7df5-7e15-47b1-8362-b42eaa95d850",
  "name": "New Name",
  "description": "saepe",
  "url": "https://google.com",
  "shippable": true,
  "purchase_type": "one_time",
  "recurring": null,
  "object": "product",
  "active": true,
  "default_price": 10000,
  "created": 1781115884,
  "updated": 1781115884,
  "livemode": false,
  "image": null,
  "metadata": {}
}

Delete product

Delete a product. Deleting a product is only possible if it has no charges associated with it.

Returns a deleted object on success. Otherwise, this call returns an error.

Path parameters
idstringrequired

Unique identifier for the product.

Returns

Returns a deleted object on success

DELETE/v1/products/{id}
curl --request DELETE \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "d09eb6e6-e9da-4831-a34f-12e111283352",
  "object": "product",
  "deleted": true
}

Search products

Search for products you've previously created using Frame's Search Query Language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages.

A dictionary with a data property that contains an array of up to limit products is returned. If no objects match the query, the resulting array will be empty.

Query parameters
namestringoptional

The product's name, meant to be displayable to the customer.

activebooleanoptional

Whether the product is currently available for purchase.

shippablebooleanoptional

Whether this product is shipped (i.e., physical goods).

pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Returns

A dictionary with a data property containing an array of matching product objects

GET/v1/products/search
curl --request GET \
  --url https://api.framepayments.com/v1/products/search \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/products/search?name=iPhone",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "products": [
    {
      "id": "d8e4c6ea-e4af-4636-a794-38c6c58625bf",
      "name": "iPhone Case",
      "description": "ipsum",
      "url": "https://google.com",
      "shippable": true,
      "purchase_type": "one_time",
      "recurring": null,
      "object": "product",
      "active": true,
      "default_price": 10000,
      "created": 1781115885,
      "updated": 1781115885,
      "livemode": false,
      "image": null,
      "metadata": {}
    }
  ]
}

List product phases

Returns the ordered list of billing phases configured on a product. These define the default phase schedule for subscriptions created from this product.

Path parameters
product_idstringrequired

Product ID

Returns

Phases retrieved

GET/v1/products/{product_id}/phases
curl --request GET \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "product_id": "26787344-04d1-44c5-b22a-b92a9594de32"
  },
  "phases": [
    {
      "id": "16b5e1c0-ce77-45fd-8735-c666482bece6",
      "ordinal": 1,
      "name": null,
      "pricing_type": "static",
      "discount_percentage": null,
      "period_count": 3,
      "phaseable_type": "Product",
      "phaseable_id": "26787344-04d1-44c5-b22a-b92a9594de32",
      "started_at": null,
      "amount": 5000,
      "currency": "USD",
      "object": "subscription_phase",
      "created": 1781115887,
      "updated": 1781115887,
      "livemode": true
    }
  ]
}

Create a product phase

Adds a billing phase to a product. Phases define scheduled pricing tiers for subscriptions — e.g. a free trial period followed by an introductory discount, then regular pricing.

Path parameters
product_idstringrequired

Product ID

Query parameters
ordinalintegerrequired

Phase position (must be unique within this product)

pricing_typestringrequired

static or relative

amount_centsintegeroptional

Fixed price in cents. Required for static pricing.

discount_percentagenumberoptional

Discount percentage (0–100). Required for relative pricing.

period_countintegeroptional

Number of billing periods. Null for an indefinite phase.

namestringoptional

Optional label (e.g. Free Trial)

Returns

Phase created

POST/v1/products/{product_id}/phases
curl --request POST \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "1823147d-b663-4cbc-9cf9-5b80e8e182f6",
  "ordinal": 1,
  "name": "Free Trial",
  "pricing_type": "relative",
  "discount_percentage": "100.0",
  "period_count": 1,
  "phaseable_type": "Product",
  "phaseable_id": "3267796d-a420-411c-909a-a7835a5e089a",
  "started_at": null,
  "amount": null,
  "currency": "USD",
  "object": "subscription_phase",
  "created": 1781115887,
  "updated": 1781115887,
  "livemode": false
}

Retrieve a product phase

Retrieves a single billing phase from a product.

Path parameters
product_idstringrequired

Product ID

idstringrequired

Phase ID

Returns

Phase retrieved

GET/v1/products/{product_id}/phases/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "19fd8541-c1f5-49d0-927d-3b30ad99e667",
  "ordinal": 2,
  "name": null,
  "pricing_type": "static",
  "discount_percentage": null,
  "period_count": 3,
  "phaseable_type": "Product",
  "phaseable_id": "d8f219be-74fb-43cd-b115-956223779212",
  "started_at": null,
  "amount": 5000,
  "currency": "USD",
  "object": "subscription_phase",
  "created": 1781115888,
  "updated": 1781115888,
  "livemode": true
}

Update a product phase

Updates a billing phase on a product.

Path parameters
product_idstringrequired

Product ID

idstringrequired

Phase ID

Query parameters
namestringoptional
period_countintegeroptional
discount_percentagenumberoptional
amount_centsintegeroptional
Returns

Phase updated

PATCH/v1/products/{product_id}/phases/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "f29cb66b-438f-46c6-b0f4-c88577794724",
  "ordinal": 3,
  "name": "Updated Trial",
  "pricing_type": "static",
  "discount_percentage": null,
  "period_count": 3,
  "phaseable_type": "Product",
  "phaseable_id": "33af0971-0905-4132-ab76-e6be61512865",
  "started_at": null,
  "amount": 5000,
  "currency": "USD",
  "object": "subscription_phase",
  "created": 1781115888,
  "updated": 1781115888,
  "livemode": true
}

Delete a product phase

Removes a billing phase from a product.

Path parameters
product_idstringrequired

Product ID

idstringrequired

Phase ID

DELETE/v1/products/{product_id}/phases/{id}
curl --request DELETE \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'

Bulk update product phases

Replaces the full phase schedule for a product in a single operation. Send an ordered array of phase objects; existing phases not included will be removed.

Path parameters
product_idstringrequired

Product ID

Body parameters
phasesarrayrequired

Ordered array of phase objects.

Returns

Phases updated

PATCH/v1/products/{product_id}/phases/bulk_update
curl --request PATCH \
  --url https://api.framepayments.com/v1/products/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/bulk_update \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "phases": [
    {}
  ]
}'
RESPONSE
{
  "meta": {
    "product_id": "d3e44a50-5805-4f53-8175-616547d65261",
    "updated_count": 1
  },
  "phases": [
    {
      "id": "9f9e04b4-cfff-44d8-b653-59a1ee97fbdc",
      "ordinal": 1,
      "name": "Free Trial",
      "pricing_type": "relative",
      "discount_percentage": "100.0",
      "period_count": 1,
      "phaseable_type": "Product",
      "phaseable_id": "d3e44a50-5805-4f53-8175-616547d65261",
      "started_at": null,
      "amount": null,
      "currency": "USD",
      "object": "subscription_phase",
      "created": 1781115888,
      "updated": 1781115888,
      "livemode": false
    }
  ]
}