# Prices > Set how much a product costs and how often it renews: every day, week, month or year. Source: https://abuna.app/docs/api/prices Prices set how much a product costs and how often it renews: every day, week, month or year. A product can have several prices, for example a monthly and a yearly one. ## The price object **Attributes** - `id` (string): Unique identifier for the price. - `product_id` (string): The product the price belongs to. - `name` (string): The price's name, for example Monthly. - `currency` (string): `XAF`, `XOF` or `USD`. - `amount` (integer): What the customer pays each billing period, in the currency's smallest unit: francs for XAF and XOF, cents for USD. - `interval` (string): The unit of a billing period: `day`, `week`, `month` or `year`. - `interval_count` (integer): How many intervals make up one billing period. `month` with `3` bills every 3 months. - `created_at` (timestamp): When the price was created, in Unix seconds. - `trial_days` (integer, nullable): Default free trial length, from 1 to 365 days. Null means no trial. Set at creation and cannot be changed. - `archived_at` (timestamp, nullable): When the price was archived. An archived price starts no new subscriptions. - `pending_change` (object, nullable): The amount change [scheduled](https://abuna.app/docs/api/prices.md#change) for the price, or null when none is. A price has at most one. - `id` (string): Unique identifier for the change. Price change events carry it as price_change_id. - `amount` (integer): The new amount, in the currency's smallest unit. - `previous_amount` (integer): The amount before the change. - `currency` (string): The price's currency. - `effective_at` (timestamp): Midnight at the start of the day the new amount applies from, in timezone. - `timezone` (string): Your app's time zone, for example `Africa/Douala`, the same as the app's [`timezone`](https://abuna.app/docs/api/apps.md#object). `effective_at` is midnight there. - `keep_current_subscribers` (boolean): `true` when everyone subscribed on that day keeps the old amount. - `created_at` (timestamp): When the change was scheduled, in Unix seconds. **The price object** ```json { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "trial_days": null, "created_at": 1727600000, "archived_at": null, "pending_change": null } ``` ## Create a price `POST /v1/apps/{appID}/prices` Creates a price for one of the app's products. Customers pay by mobile money in FCFA, whatever the price's currency. A USD price is charged at the day's exchange rate plus 2%, rounded up to a whole franc, and the 2% is part of what you receive. Between XOF and XAF the amount converts 1 to 1. The rate is saved on each payment. See [Paying in FCFA](https://abuna.app/docs/amounts-currencies-and-timestamps.md#paying-in-fcfa). **Parameters** - `product_id` (string, required): The product to price. - `name` (string, required): The price's name, for example Monthly. - `currency` (string, required): `XAF`, `XOF` or `USD`. Lowercase works too. - `amount` (integer, required): What the customer pays each billing period, in the currency's smallest unit: francs for XAF and XOF, cents for USD, so `1000` is $10.00. Must be greater than 0. - `interval` (string, required): `day`, `week`, `month` or `year`. - `trial_days` (integer): Optional free trial length, from 1 to 365 days. Omit it or send `null` for no trial. It cannot be changed later. See [Free trials](https://abuna.app/docs/guides/trials.md). - `interval_count` (integer): How many intervals make up one billing period. Defaults to `1`. At most 365 days, 52 weeks, 12 months or 1 year. Returns the price with status `201`. An invalid field returns `422` with code `invalid`. If the app has no product with that `product_id`, returns `404` with code `not_found` and an `errors` item for `product_id`. **POST /v1/apps/{appID}/prices** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/prices \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month"}' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/prices", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ product_id: "pR4dWx9K", name: "Monthly", currency: "XAF", amount: 5000, interval: "month" }), }); const price = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/prices", headers={"Authorization": "Bearer sk_test_..."}, json={"product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month"}, ) price = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["product_id" => "pR4dWx9K", "name" => "Monthly", "currency" => "XAF", "amount" => 5000, "interval" => "month"]), CURLOPT_RETURNTRANSFER => true, ]); $price = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{"product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month"}) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/prices", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var price map[string]any json.NewDecoder(res.Body).Decode(&price) ``` **Response** ```json { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "trial_days": null, "created_at": 1727600000, "archived_at": null, "pending_change": null } ``` ## List prices `GET /v1/apps/{appID}/prices` Lists the app's prices, across all products and including archived ones, newest first, one page at a time. **Query parameters** - `limit` (integer): How many prices to return, from 1 to 100. Defaults to 50. - `cursor` (string): The `next_cursor` from the previous page. Send the same filters with it. Returns `items` and `next_cursor`, as described in [Lists and filters](https://abuna.app/docs/lists-and-filters.md#pages). A value that isn't allowed, like a `limit` above 100, returns `422` with code `invalid` and the parameter's name in `errors`. **GET /v1/apps/{appID}/prices** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/prices \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/prices", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/prices", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/prices", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Response** ```json { "items": [ { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "trial_days": null, "created_at": 1727600000, "archived_at": null, "pending_change": null } ], "next_cursor": null } ``` ## Update a price `PATCH /v1/apps/{appID}/prices/{id}` Renames the price. Its amount, currency, billing period and checkout link stay the same. To change what customers pay, [schedule a price change](https://abuna.app/docs/api/prices.md#change). The trial length cannot change. Create a new price to set a different `trial_days` default. **Parameters** - `name` (string, required): The new name, for example Monthly plan. Returns the price. A blank name returns `422` with code `invalid`. If the app has no price with that ID, returns `404` with code `not_found`. **PATCH /v1/apps/{appID}/prices/{id}** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q \ -X PATCH \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"name": "Monthly plan"}' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q", { method: "PATCH", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ name: "Monthly plan" }), }); const price = await response.json(); ``` Python: ```python import requests response = requests.patch( "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q", headers={"Authorization": "Bearer sk_test_..."}, json={"name": "Monthly plan"}, ) price = response.json() ``` PHP: ```php "PATCH", CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["name" => "Monthly plan"]), CURLOPT_RETURNTRANSFER => true, ]); $price = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]string{"name": "Monthly plan"}) req, _ := http.NewRequest("PATCH", "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var price map[string]any json.NewDecoder(res.Body).Decode(&price) ``` **Response** ```json { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly plan", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "trial_days": null, "created_at": 1727600000, "archived_at": null, "pending_change": null } ``` ## Archive a price `POST /v1/apps/{appID}/prices/{id}/archive` Archives the price. It starts no new subscriptions, and subscriptions already on it keep renewing. Archiving an archived price changes nothing. To undo it, [unarchive the price](https://abuna.app/docs/api/prices.md#unarchive). Returns the price. If the app has no price with that ID, returns `404` with code `not_found`. **POST /v1/apps/{appID}/prices/{id}/archive** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/archive \ -X POST \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/archive", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const price = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/archive", headers={"Authorization": "Bearer sk_test_..."}, ) price = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $price = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/archive", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var price map[string]any json.NewDecoder(res.Body).Decode(&price) ``` **Response** ```json { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "trial_days": null, "created_at": 1727600000, "archived_at": 1727686400, "pending_change": null } ``` ## Unarchive a price `POST /v1/apps/{appID}/prices/{id}/unarchive` Unarchives the price. It can start new subscriptions again, and its checkout link works again. Unarchiving a price that isn't archived changes nothing. Returns the price. If the app has no price with that ID, returns `404` with code `not_found`. **POST /v1/apps/{appID}/prices/{id}/unarchive** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/unarchive \ -X POST \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/unarchive", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const price = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/unarchive", headers={"Authorization": "Bearer sk_test_..."}, ) price = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $price = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/unarchive", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var price map[string]any json.NewDecoder(res.Body).Decode(&price) ``` **Response** ```json { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "trial_days": null, "created_at": 1727600000, "archived_at": null, "pending_change": null } ``` ## Schedule a price change `POST /v1/apps/{appID}/prices/{id}/change` Schedules a new amount for the price, starting on a day at least 14 days ahead. The amount never changes right away. The currency and billing period can't change. For a different one, [create a new price](https://abuna.app/docs/api/prices.md#create). From the start of that day in your app's time zone, checkouts and new subscriptions pay the new amount. Each current subscriber pays it from their first renewal on or after that day. Abuna emails each of them now with the amount they will pay, after any discount they hold, and the date it first applies to them, and messages them on Telegram if they chose it. Customers who subscribe while the change is pending get the same message when they subscribe. With `keep_current_subscribers`, everyone subscribed on that day keeps paying the old amount for as long as they stay subscribed, and only later subscribers pay the new one. A subscriber who moves to another price and back pays the price's amount at that time. A price has one pending change. Scheduling another replaces it. If the replacement keeps current subscribers on the old amount, those told about the earlier change get an email saying their price stays. Abuna records a `price_change.scheduled` [event](https://abuna.app/docs/api/events.md#price-change-scheduled), and `price_change.applied` when the new amount starts. **Parameters** - `amount` (integer, required): The new amount, in the currency's smallest unit. Must be greater than 0 and different from the current amount. - `effective_at` (timestamp, required): Any time on the day the new amount starts, in Unix seconds. Abuna moves it to the start of that day in your app's time zone. The day must be at least 14 days after today there. - `keep_current_subscribers` (boolean): Keep everyone subscribed on that day on the old amount. Defaults to `false`. Returns the price with `pending_change` set. A failed check returns `422` with code `invalid`, and each `errors` item names the field: `amount` with `invalid` or `unchanged`, or `effective_at` with `required` or `too_soon`. Any other field, such as `currency` or `interval`, returns `400` with code `invalid_json`. If the app has no price with that ID, returns `404` with code `not_found`. Once the pending change reaches its `effective_at`, it can't be replaced until it is applied, and the request returns `409` with code `change_in_effect`. See [When the change takes effect](https://abuna.app/docs/api/prices.md#change-in-effect). **POST /v1/apps/{appID}/prices/{id}/change** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change \ -X POST \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"amount": 6000, "effective_at": 1730458800, "keep_current_subscribers": false}' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ amount: 6000, effective_at: 1730458800, keep_current_subscribers: false }), }); const price = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change", headers={"Authorization": "Bearer sk_test_..."}, json={"amount": 6000, "effective_at": 1730458800, "keep_current_subscribers": False}, ) price = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["amount" => 6000, "effective_at" => 1730458800, "keep_current_subscribers" => false]), CURLOPT_RETURNTRANSFER => true, ]); $price = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{"amount": 6000, "effective_at": 1730458800, "keep_current_subscribers": false}) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var price map[string]any json.NewDecoder(res.Body).Decode(&price) ``` **Response** ```json { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "trial_days": null, "created_at": 1727600000, "archived_at": null, "pending_change": { "id": "W4hN7gPc", "amount": 6000, "previous_amount": 5000, "currency": "XAF", "effective_at": 1730415600, "timezone": "Africa/Douala", "keep_current_subscribers": false, "created_at": 1727700000 } } ``` ## Cancel a price change `POST /v1/apps/{appID}/prices/{id}/change/cancel` Cancels the price's pending change, so the amount stays as it is. If current subscribers were going to move to the new amount, Abuna emails them that their price stays. Abuna records a `price_change.canceled` [event](https://abuna.app/docs/api/events.md#price-change-canceled). Returns the price with `pending_change` set to null. If the app has no price with that ID, returns `404` with code `not_found`. With no pending change, returns `409` with code `no_pending_change`. Once the change reaches its `effective_at`, it can't be canceled, and the request returns `409` with code `change_in_effect`. **POST /v1/apps/{appID}/prices/{id}/change/cancel** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change/cancel \ -X POST \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change/cancel", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const price = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change/cancel", headers={"Authorization": "Bearer sk_test_..."}, ) price = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $price = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/prices/Zt6YbN3q/change/cancel", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var price map[string]any json.NewDecoder(res.Body).Decode(&price) ``` **Response** ```json { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "trial_days": null, "created_at": 1727600000, "archived_at": null, "pending_change": null } ``` ## When the change takes effect A change takes effect at its `effective_at`, and Abuna records `price_change.applied` within about a minute of that time. In between, `pending_change` still shows the change, and canceling or replacing it returns `409` with code `change_in_effect`. Once `price_change.applied` is recorded, `pending_change` is null and you can schedule a new change.