Bläddra API:et per resurs.

Octany-API:et hanterar prenumerationer, produkter, ordrar och webhook-endpoints. Den här sidan är till för dig som vill förstå API:et som människa. Behöver du maskinläsbara typer hittar du dem i OpenAPI-specen.

§ 04.1 Grunderna #

Bas-URL

https://app.octany.com/api/{account}

Autentisering

X-API-KEY: <din-api-nyckel>
X-Locale: sv

API-nycklar är scopade till ett konto. Sätt X-Locale om du vill ha valideringsmeddelanden och formaterade strängar på ett specifikt språk.

Resurs-ID:n

id-värdena på Subscription, Order och webhook-leveranser är heltal i produktion idag (t.ex. 76963688). Hantera dem som opaka identifierare i lagringen — använd en kolumn som rymmer en framtida formatändring (sträng eller bigint). Validera inte formatet och bygg inte logik kring is_int/typeof === 'number'; skicka tillbaka dem precis som du fick dem. Produkt-ID:n är heltal och kommer rimligtvis inte byta format. Konto-ID i URL-pathar är numeriska idag också; behandla dem som opaka.

Paginering

List-endpoints returnerar data plus pagination. Använd ?page=2 för att bläddra vidare. Skicka X-Locale: sv om du vill ha svenska felmeddelanden och valideringstexter.

{
  "data": [],
  "pagination": {
    "total": 142,
    "count": 20,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 8,
    "links": { "next": "https://app.octany.com/api/{account}/subscriptions?page=2" }
  }
}

§ 04.2 Subscriptions #

Subscriptions står för återkommande fakturering av en produkt. Spara prenumerationens id när subscription.created kommer fram — sedan kan du använda det för uppsägning, engångsordrar eller produktbyte.

curl "https://app.octany.com/api/$ACCOUNT/subscriptions?filter[reference_id]=user_42" \
  -H "X-API-KEY: $OCTANY_KEY"

curl "https://app.octany.com/api/$ACCOUNT/subscription/76963688" \
  -H "X-API-KEY: $OCTANY_KEY"

curl -X POST "https://app.octany.com/api/$ACCOUNT/subscription/76963688/cancel" \
  -H "X-API-KEY: $OCTANY_KEY"

curl -X POST "https://app.octany.com/api/$ACCOUNT/subscription/76963688/product" \
  -H "X-API-KEY: $OCTANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": 42 }'

curl "https://app.octany.com/api/$ACCOUNT/subscription/76963688/orders?filter[state]=paid&per_page=50" \
  -H "X-API-KEY: $OCTANY_KEY"

curl -X POST "https://app.octany.com/api/$ACCOUNT/subscription/76963688/order" \
  -H "X-API-KEY: $OCTANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "product_id": 89,
        "amount": 4995,
        "quantity": 1,
        "vat": 2500,
        "description": "Extra item"
      }'

§ 04.3 Orders #

curl "https://app.octany.com/api/$ACCOUNT/order/516253755" \
  -H "X-API-KEY: $OCTANY_KEY"

Order-status

§ 04.4 Products #

curl "https://app.octany.com/api/$ACCOUNT/products" \
  -H "X-API-KEY: $OCTANY_KEY"

curl "https://app.octany.com/api/$ACCOUNT/product/42" \
  -H "X-API-KEY: $OCTANY_KEY"

curl -X POST "https://app.octany.com/api/$ACCOUNT/product/42" \
  -H "X-API-KEY: $OCTANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Månadsmedlemskap",
        "description": "Tillgång till medlemsinnehåll.",
        "price": 9900,
        "currency": "SEK",
        "vat_rate": 25,
        "interval": "month"
      }'

curl -X DELETE "https://app.octany.com/api/$ACCOUNT/product/42" \
  -H "X-API-KEY: $OCTANY_KEY"

§ 04.5 Webhook-endpoints #

curl -X POST "https://app.octany.com/api/$ACCOUNT/webhooks/endpoints" \
  -H "X-API-KEY: $OCTANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://app.example.com/octany/webhook" }'

§ 04.6 Payload-form #

Subscription — statuslivscykel

Åtta värden: pending, future_start, trialing, active, delayed, unpaid, cancelled, expired. Det finns två övergångar som ofta krånglar till det för integratörer:

• delayed är övergående (Octany retryar förnyelsen); unpaid är terminal (admin måste agera). Stäng inte av åtkomst på delayed.
• cancelled betyder inte "stäng av åtkomsten nu" — stängningen ska gå mot ends_at. ends_at: null betyder ingen stängning ännu.

Den enda boolean de flesta integratörer faktiskt vill ha:

function isPaying(string $status, ?DateTimeInterface $endsAt): bool
{
    return in_array($status, ['active', 'trialing'], true)
        && ($endsAt === null || $endsAt > new DateTime());
}

Allt annat — delayed, unpaid, pending, expired, cancelled efter ends_at — är "ingen åtkomst". Se integration.md för hela livscykeldiagrammet.

Subscription

{
  "id": 76963688,
  "price": 9900,
  "vat": 2500,
  "currency": "SEK",
  "renews_at": "2026-05-25T09:29:51+00:00",
  "reference_id": "member_42",
  "reference_name": "Anna Persson",
  "status": "active",
  "update_card_url": "https://octanybilling.com/...",
  "invoices_url": "https://octanybilling.com/...",
  "cancel_url": "https://octanybilling.com/...",
  "custom_fields": [],
  "metadata": {}
}

Order

{
  "id": 516253755,
  "total": 7920,
  "total_with_vat": 9900,
  "currency": "SEK",
  "reference_id": "member_42",
  "state": "paid",
  "delivery": { "link": "https://..." },
  "custom_fields": [],
  "metadata": {}
}

Product

{
  "id": 42,
  "name": "Månadsmedlemskap",
  "description": "Tillgång till medlemsinnehåll.",
  "type": "Recurring",
  "price": 9900,
  "price_with_vat": 9900,
  "price_without_vat": 7920,
  "currency": "SEK",
  "vat_rate": 25,
  "interval": "month",
  "use_cart": true,
  "stock_tracking": false,
  "out_of_stock": false
}