API reference
Products
Create, list and rename what you sell, and copy it between Test and Live.
Products are what you sell. Each product has one or more prices that set what customers pay.
The product object
Attributes
idstringUnique identifier for the product.app_idstringThe app the product belongs to.namestringThe product's name.slugstringA URL-safe name, unique within the app. It doesn't change when you rename the product, so your code can rely on it. It changes only when you set a new one.created_attimestampWhen the product was created, in Unix seconds.archived_attimestampnullableWhen the product was archived, or null. An archived product starts no new subscriptions on any of its prices.
{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}Create a product
POST/v1/apps/{appID}/products
Accepts an Idempotency-Key header.
Creates a product.
Parameters
namestringrequiredThe product's name.slugstringThe slug to use: lowercase letters and digits, with single hyphens between them, up to 100 characters. Without one, Abuna makes it fromname. If that slug is taken, it adds-2,-3, and so on, so a product created without a slug never conflicts.
Returns the product with status 201. A slug in the wrong form returns 422 with code invalid and an errors item for slug. If another product in the app has the slug you sent, returns 409 with code slug_taken and an errors item for slug.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"name": "Pro plan"}'{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}List products
GET/v1/apps/{appID}/products
Lists the app's products, including archived ones, newest first, one page at a time.
Query parameters
limitintegerHow many products to return, from 1 to 100. Defaults to 50.cursorstringThenext_cursorfrom the previous page. Send the same filters with it.
Returns items and next_cursor, as described in Lists and filters. A value that isn't allowed, like a limit above 100, returns 422 with code invalid and the parameter's name in errors.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}
],
"next_cursor": null
}Update a product
PATCH/v1/apps/{appID}/products/{id}
Changes the product's name, its slug, or both. Send at least one. A new name keeps the current slug.
Parameters
namestringThe new name.slugstringThe new slug, in the same form as on create.
Returns the product. A body with neither field, or a blank name, returns 422 with code invalid and an errors item for name. A slug in the wrong form returns 422 with an errors item for slug. If another product in the app has the new slug, returns 409 with code slug_taken and an errors item for slug. If the app has no product with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/pR4dWx9K \
-X PATCH \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"name": "Team plan"}'{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Team plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}Archive a product
POST/v1/apps/{appID}/products/{id}/archive
Accepts an Idempotency-Key header.
Archives the product. Its prices start no new subscriptions, and their checkout links show “This plan is no longer available.” Subscriptions already on its prices keep renewing. Each price keeps its own archived state. Archiving an archived product changes nothing. To undo it, unarchive the product.
Returns the product. If the app has no product with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/pR4dWx9K/archive \
-X POST \
-H "Authorization: Bearer sk_test_..."{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": 1727686400
}Unarchive a product
POST/v1/apps/{appID}/products/{id}/unarchive
Accepts an Idempotency-Key header.
Unarchives the product. Its prices that aren't archived can start new subscriptions again, and their checkout links work again. Prices you archived yourself stay archived. Unarchiving a product that isn't archived changes nothing.
Returns the product. If the app has no product with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/pR4dWx9K/unarchive \
-X POST \
-H "Authorization: Bearer sk_test_..."{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}Copy between Test and Live
You can copy products and their prices from your app's Test mode to its Live mode, and from Live back to Test. Call the endpoint on the app you copy to: copy from Test on the Live app, or copy from Live on the Test app. Both take the same body and return the same response.
A new copy of a product gets its name and slug. A new copy of a price gets its name, currency, amount and billing period. Copying again brings a product's name and slug, and a price's name and amount, up to date with the app you copy from.
Copies are linked both ways
Once a product is copied, it and its copy stay paired, whichever way you copy next. Copying either one updates the other and never makes a new product. Prices are paired the same way.
For example, build a product in Test and copy it to Live. Rename it in Live, then copy it from Live to Test. The original Test product gets the new name, and no second Test product appears. A product you build in Live and copy to Test works the same way.
What you can rely on, in both directions:
- It copies only when you call it, and only into the app in the path.
- It copies products and prices only. Customers, subscriptions, and settings stay as they are.
- Copying again updates the copies made before, whichever way they were made. It never makes a second copy.
- It never deletes, archives or unarchives anything in the app you copy to. A product or price that's gone from the app you copy from, or a price archived there, stays as it is.
- A changed amount never applies right away, in Test or in Live, and current subscribers keep what they pay. See Changed amounts.
- It copies everything or nothing: a request that fails changes nothing. Skipped products and prices don't make it fail.
- With
dry_run, it returns what the copy would do and changes nothing. - A retry with the same
Idempotency-Keyreturns the first response and copies nothing again.
Copy products from Test to Live
POST/v1/apps/{appID}/products/copy-from-test
Accepts an Idempotency-Key header.
Copies products and their prices from the Test app to the Live app. Call it with the Live app's ID, live_app_id, and a Live secret key. A Test key can't call it and gets 404 with code not_found. See Copy between Test and Live for what a copy changes.
Parameters
productsarrayThe IDs of the Test products to copy, from 1 to 100. Sendproductsorall, not both.allbooleantruecopies every product in the Test app.dry_runbooleanReturn what the copy would do, with the same statuses, without changing anything. Defaults tofalse.
Response attributes
dry_runbooleantruewhen this was a dry run and nothing changed.productsarrayOne item per product, in the order you sent them. Withall, the products in the app you copy from, oldest first, then the copies whose product is gone from it.Show child attributesHide child attributes
test_idstringnullableThe product's ID in Test. Null when you copy from Live and the product has no Test copy yet.live_idstringnullableThe product's ID in Live. Null when you copy from Test and the product has no Live copy yet.namestringThe product's name.statusstringreasonstringnullableWhy the product was skipped:not_found,deletedorslug_taken. Null unlessstatusisskipped.pricesarrayThe product's prices, each with the attributes below.Show child attributesHide child attributes
test_idstringnullableThe price's ID in Test. Null when you copy from Live and the price has no Test copy yet.live_idstringnullableThe price's ID in Live. Null when you copy from Test and the price has no Live copy yet.namestringThe price's name.statusstringcreated,updated,unchangedorskipped.reasonstringnullableWhy the price was skipped:archived,deletedorpending_change. Null unlessstatusisskipped.price_changeobjectnullableThe amount change this copy scheduled in the app you copy to, or null when it scheduled none.Show child attributesHide child attributes
amountintegerThe new amount, in the currency's smallest unit.currencystringXAF,XOForUSD.effective_attimestampMidnight at the start of the day the new amount applies from, in your app's time zone.
Returns 200. Without products or all, returns 422 with code invalid and an errors item for products with code required. Sending both, an empty list, more than 100 IDs, or a blank ID returns 422 with an errors item for products with code invalid. A Test app ID in the path returns 400 with code live_app_required. If the app has no Test mode, returns 409 with code test_app_missing. Until the team owner verifies their email, returns 403 with code email_unverified. If your team's plan made the Live app read-only, returns 403 with code plan_read_only.
curl https://api.abuna.app/v1/apps/Q7mKp2Rt/products/copy-from-test \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: b7e2c1d4-8f3a-4e6b-9c5d-1a2f3e4b5c6d" \
-d '{
"all": true
}'{
"dry_run": false,
"products": [
{
"test_id": "pR4dWx9K",
"live_id": "Lq2VnB8s",
"name": "Pro plan",
"status": "updated",
"reason": null,
"prices": [
{
"test_id": "Zt6YbN3q",
"live_id": "Hm5RcT9w",
"name": "Monthly",
"status": "updated",
"reason": null,
"price_change": {
"amount": 6000,
"currency": "XAF",
"effective_at": 1792450800
}
},
{
"test_id": "Yc3KfP7d",
"live_id": "Ub8NsE2x",
"name": "Yearly",
"status": "created",
"reason": null,
"price_change": null
},
{
"test_id": "Wk9DgA4m",
"live_id": null,
"name": "Weekly",
"status": "skipped",
"reason": "archived",
"price_change": null
}
]
}
]
}Copy products from Live to Test
POST/v1/apps/{appID}/products/copy-from-live
Accepts an Idempotency-Key header.
Copies products and their prices from the Live app to the Test app. Call it with the Test app's ID, test_app_id, and a Test secret key. A Live key can't call it and gets 404 with code not_found. See Copy between Test and Live for what a copy changes.
It takes the same body and returns the same response as copy from Test, with Live and Test swapped. products takes Live product IDs, and all copies every product in the Live app. In the response, live_id is always set: it's the product or price you copied. test_id is its Test copy, or null when it has none yet.
It only reads from Live, so it works even before the team owner verifies their email, and when your team's plan has made the Live app read-only.
Returns 200. The body is checked as in copy from Test, with the same 422 errors. A Live app ID in the path returns 400 with code test_app_required.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/copy-from-live \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 4f9a2c7e-1b3d-4e8f-a6c5-9d2e7b1f3a8c" \
-d '{
"all": true
}'{
"dry_run": false,
"products": [
{
"test_id": "pR4dWx9K",
"live_id": "Lq2VnB8s",
"name": "Team plan",
"status": "updated",
"reason": null,
"prices": [
{
"test_id": "Zt6YbN3q",
"live_id": "Hm5RcT9w",
"name": "Monthly",
"status": "unchanged",
"reason": null,
"price_change": null
},
{
"test_id": "Jr7WqC5v",
"live_id": "Fs4HxM8p",
"name": "Daily",
"status": "created",
"reason": null,
"price_change": null
}
]
}
]
}Copy results
Below, a product's or price's copy is its pair in the app you copy to. When you copy something back to where it came from, its copy is the original. Each product in the response has one of these statuses:
created: the product had no copy, and now has one.updated: its copy's name or slug changed, or one of its prices was created or updated.unchanged: nothing changed, though some of its prices may be skipped.skipped, with areason:not_found: the ID you sent isn't a product in the app you copy from.deleted: withallonly. The product is gone from the app you copy from. Its copy stays as it is.slug_taken: another product in the app you copy to already has this product's slug. Nothing is copied for this product or its prices. Change one of the two slugs, then copy again.
Each price has one of these statuses:
created: the price had no copy, and now has one under the product's copy.updated: its copy was renamed, had an amount change scheduled, or both.unchanged: nothing changed.skipped, with areason:archived: the price is archived in the app you copy from. Its copy, if it has one, stays as it is.deleted: the price is gone from the app you copy from. Its copy stays as it is.pending_change: its copy already has a scheduled change to a different amount. Nothing is copied for this price. To copy the amount, cancel that change, then copy again.
Changed amounts
When a price's amount differs from its copy's, Abuna schedules a price change on the copy, with keep_current_subscribers. This works the same in Test and in Live. The new amount starts on the earliest day allowed, 14 days after today in your app's time zone. Everyone subscribed before that day keeps paying the current amount, and customers who subscribe from that day pay the new one. Abuna records a price_change.scheduled event in the app you copy to, and the price's price_change in the response shows the new amount and the day it starts.
A price that already has a scheduled change is copied with that change: Abuna compares the amount it's moving to, and the copy moves to it on the same day, or on the earliest day allowed if that's later. A new copy starts at the current amount with the same change scheduled. So copying a price back before its change starts leaves the original as it is.
If the copy already has a scheduled change, Abuna never replaces or cancels it. If that change is to the same amount, there's nothing more to do. If it's to a different amount, the price is skipped with pending_change.