Packages API

Monthly packages that bundle services and classes, with sessions counted.

Module code packages · 7 actions · 3 data models · 6 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: packages (everything), packages:read (read only) or packages:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

packages.create_package

Create a package — A period, a price and what it covers.

Needs packages:manage · changes data

• REST alias: POST /api/v1/packages
• Canonical address: POST /api/v1/actions/packages.create_package

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: packages.package_created

What it writes: package (insert) — Creates the package; package_item (insert) — Writes what it covers

curl -X POST https://app.getera.io/api/v1/packages/actions/create_package \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name","periodMonths":1,"priceAmount":1,"items":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "packages.package_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.packages.create({
  name: "Name",
  periodMonths: 1,
  priceAmount: 1,
  items: {}
})

era packages create --data '{"name":"Name","periodMonths":1,"priceAmount":1,"items":{}}'

{
  "name": "era__packages__create_package",
  "arguments": {
    "name": "Name",
    "periodMonths": 1,
    "priceAmount": 1,
    "items": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold packages:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_items, service_not_found, class_not_found · 429 slow down

packages.redeem

Use a package session — Covers a booking from a subscription, while it has sessions left.

Needs packages:write · changes data

• Canonical address: POST /api/v1/actions/packages.redeem

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: packages.session_used, packages.almost_used_up

What it writes: package_usage (insert) — Records the session drawn

curl -X POST https://app.getera.io/api/v1/package_usages/actions/redeem \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"subscriptionId":"SUBSCRIPTION_ID","recordType":"appointment_line","recordId":"RECORD_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "packages.session_used",
    "packages.almost_used_up"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.packageUsages.redeem({
  subscriptionId: "SUBSCRIPTION_ID",
  recordType: "appointment_line",
  recordId: "RECORD_ID"
})

era package_usages redeem \
  --subscription-id "SUBSCRIPTION_ID" \
  --record-type "appointment_line" \
  --record-id "RECORD_ID"

{
  "name": "era__packages__redeem",
  "arguments": {
    "subscriptionId": "SUBSCRIPTION_ID",
    "recordType": "appointment_line",
    "recordId": "RECORD_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold packages:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 subscription_not_found, subscription_not_active, record_not_found, customer_mismatch, subscription_expired, not_covered, already_redeemed, no_sessions_left · 429 slow down

packages.release

Give a session back — Undoes a session drawn by mistake. The booking itself is not touched.

Needs packages:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/packages.release

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: packages.session_released

What it writes: package_usage (delete) — Removes the usage

curl -X POST https://app.getera.io/api/v1/package_usages/PACKAGE_USAGE_ID/actions/release \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "packages.session_released"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.packageUsages.release("PACKAGE_USAGE_ID")

era package_usages release PACKAGE_USAGE_ID

{
  "name": "era__packages__release",
  "arguments": {
    "usageId": "PACKAGE_USAGE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold packages:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 usage_not_found · 429 slow down

packages.retire_package

Take off sale — Stops selling it. Running subscriptions carry on to their end dates.

Needs packages:manage · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/packages.retire_package

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: packages.package_retired

What it writes: package (update) — Stamps archived_at

curl -X POST https://app.getera.io/api/v1/packages/PACKAGE_ID/actions/retire_package \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "packages.package_retired"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.packages.retirePackage("PACKAGE_ID")

era packages retire_package PACKAGE_ID

{
  "name": "era__packages__retire_package",
  "arguments": {
    "id": "PACKAGE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold packages:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, package_retired · 429 slow down

packages.set_items

Change what it covers — The services and classes in the package, with how many sessions each.

Needs packages:manage · removes or cannot be undone

• Canonical address: POST /api/v1/actions/packages.set_items

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: packages.package_updated

What it writes: package_item (delete) — Clears the old contents; package_item (insert) — Writes the new contents

curl -X POST https://app.getera.io/api/v1/package_items/actions/set_items \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"PACKAGE_ID","items":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "packages.package_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.packageItems.setItems({
  id: "PACKAGE_ID",
  items: {}
})

era package_items set_items --data '{"id":"PACKAGE_ID","items":{}}'

{
  "name": "era__packages__set_items",
  "arguments": {
    "id": "PACKAGE_ID",
    "items": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold packages:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, package_retired, invalid_items, service_not_found, class_not_found, items_in_use · 429 slow down

packages.update_package

Edit a package — Name, period, price and renewal default — for new sales only.

Needs packages:manage · changes data

• REST alias: PATCH /api/v1/packages/{id}
• Canonical address: POST /api/v1/actions/packages.update_package

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: packages.package_updated

What it writes: package (update) — Updates the package

curl -X POST https://app.getera.io/api/v1/packages/PACKAGE_ID/actions/update_package \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "packages.package_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.packages.updatePackage("PACKAGE_ID", {
  name: "Name"
})

era packages update_package PACKAGE_ID \
  --name "Name"

{
  "name": "era__packages__update_package",
  "arguments": {
    "id": "PACKAGE_ID",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold packages:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, package_retired · 429 slow down

packages.use_on_my_booking

Use my package — A signed-in customer covers the booking they just made from their package, while it has sessions left.

Needs packages:write · changes data · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/packages.use_on_my_booking

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: packages.session_used, packages.almost_used_up

What it writes: package_usage (insert) — Records the session drawn

Errors: 401 no or expired credential · 403 the credential does not hold packages:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_your_booking, no_sessions_left · 429 slow down

Data models

PackageItem

Table package_item · Resource package_items

• GET /api/v1/package_items
• GET /api/v1/package_items/{id}

Primary key: id

Checks:

• CHECK ((num_nonnulls(item_variant_id, group_class_id) = 1))
• CHECK (((sessions_per_period IS NULL) OR (sessions_per_period > 0)))

PackageUsage

Table package_usage · Resource package_usages

• GET /api/v1/package_usages
• GET /api/v1/package_usages/{id}

Primary key: id

Unique: record_type, record_id

Package

Table package · Resource packages

• GET /api/v1/packages
• GET /api/v1/packages/{id}
• POST /api/v1/packages → packages.create_package
• PATCH /api/v1/packages/{id} → packages.update_package

Primary key: id

Checks:

• CHECK (((length(btrim(name)) >= 1) AND (length(btrim(name)) <= 255)))
• CHECK ((period_months > 0))
• CHECK ((price_amount >= 0))

Events

Workflows and webhooks react to these events.