Skip to content
ABUNA
DocsProducts

API reference

Products

Create, list and rename what you sell, and copy it between Test and Live.

View as Markdown

Products are what you sell. Each product has one or more prices that set what customers pay.

The product object

Attributes

  • idstring

    Unique identifier for the product.
  • app_idstring

    The app the product belongs to.
  • namestring

    The product's name.
  • slugstring

    A 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_attimestamp

    When the product was created, in Unix seconds.
  • archived_attimestampnullable

    When the product was archived, or null. An archived product starts no new subscriptions on any of its prices.
The product object
{
  "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

  • namestringrequired

    The product's name.
  • slugstring

    The slug to use: lowercase letters and digits, with single hyphens between them, up to 100 characters. Without one, Abuna makes it from name. 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.

POST /v1/apps/{appID}/products
curl https://api.abuna.app/v1/apps/8ddhXCDW/products \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Pro plan"}'
Response
{
  "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

  • limitinteger

    How many products to return, from 1 to 100. Defaults to 50.
  • cursorstring

    The next_cursor from 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.

GET /v1/apps/{appID}/products
curl https://api.abuna.app/v1/apps/8ddhXCDW/products \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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

  • namestring

    The new name.
  • slugstring

    The 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.

PATCH /v1/apps/{appID}/products/{id}
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"}'
Response
{
  "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.

POST /v1/apps/{appID}/products/{id}/archive
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/pR4dWx9K/archive \
  -X POST \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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.

POST /v1/apps/{appID}/products/{id}/unarchive
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/pR4dWx9K/unarchive \
  -X POST \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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.

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-Key returns 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

  • productsarray

    The IDs of the Test products to copy, from 1 to 100. Send products or all, not both.
  • allboolean

    true copies every product in the Test app.
  • dry_runboolean

    Return what the copy would do, with the same statuses, without changing anything. Defaults to false.

Response attributes

  • dry_runboolean

    true when this was a dry run and nothing changed.
  • productsarray

    One item per product, in the order you sent them. With all, 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_idstringnullable

      The product's ID in Test. Null when you copy from Live and the product has no Test copy yet.
    • live_idstringnullable

      The product's ID in Live. Null when you copy from Test and the product has no Live copy yet.
    • namestring

      The product's name.
    • statusstring

      created, updated, unchanged or skipped. See Copy results.
    • reasonstringnullable

      Why the product was skipped: not_found, deleted or slug_taken. Null unless status is skipped.
    • pricesarray

      The product's prices, each with the attributes below.
      Show child attributesHide child attributes
      • test_idstringnullable

        The price's ID in Test. Null when you copy from Live and the price has no Test copy yet.
      • live_idstringnullable

        The price's ID in Live. Null when you copy from Test and the price has no Live copy yet.
      • namestring

        The price's name.
      • statusstring

        created, updated, unchanged or skipped.
      • reasonstringnullable

        Why the price was skipped: archived, deleted or pending_change. Null unless status is skipped.
      • price_changeobjectnullable

        The amount change this copy scheduled in the app you copy to, or null when it scheduled none.
        Show child attributesHide child attributes
        • amountinteger

          The new amount, in the currency's smallest unit.
        • currencystring

          XAF, XOF or USD.
        • effective_attimestamp

          Midnight 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.

POST /v1/apps/{appID}/products/copy-from-test
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
  }'
Response
{
  "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.

POST /v1/apps/{appID}/products/copy-from-live
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
  }'
Response
{
  "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 a reason:
    • not_found: the ID you sent isn't a product in the app you copy from.
    • deleted: with all only. 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 a reason:
    • 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.

Next steps