§ 04 — API-referens

Bläddra API:et per resurs.

Octany-API:et hanterar prenumerationer, produkter, ordrar, kontakter 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.

Baskontrakt Varje endpoint är scopad till ett konto: https://app.octany.com/api/{account}. Skicka kontots API-nyckel i headern X-API-KEY.

§ 04.1 Grunderna #

Bas-URL

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

Autentisering

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

API-nycklar är scopade till ett konto. Sätt X-Locale om du vill ha formaterade strängar på ett specifikt språk. Felmeddelanden är alltid på engelska. Skicka Octany-Version för att välja API-version för ett enskilt anrop.

API-versioner

Octany har två API-versioner. De skiljer sig i hur prenumerationer och ordrar pekar ut givaren. Använd reglaget API v1 / v2 i headern för att se exemplen på sidan i valfri version.

Version	Givaren på prenumerationer och ordrar	Används av
2	`contact`: hela kontakten, med samma form som `GET /contacts/{id}`, inklusive `metadata`. `null` när ingen kontakt är kopplad.	Nya konton, och konton som saknade API-nycklar och webhook-endpoints när versionerna infördes.
1	En referens till den gamla kundposten, som fasas ut. Prenumerationer har också länkarna till fakturaportalen, som version 2 utelämnar.	Konton som redan hade en integration.

Versionen är en kontoinställning. Du ändrar den i admin under Inställningar → API-nycklar genom att klicka på API-version. Den gäller både API-svar och webhooks. Vill du prova den andra versionen i ett enskilt anrop skickar du headern Octany-Version. Varje svar returnerar Octany-Version med versionen som användes, och ett värde som inte stöds ger 400.

Webhooks använder alltid kontots version, och leveranser i version 2 har "version": 2 i envelopet. Nya fält kan dyka upp i båda versionerna när som helst; bara ändringar som bryter integrationer får en ny version. Ändringsloggen listar alla skillnader.

Byta till version 2 Skicka Octany-Version: 2 från en integration i taget och läs contact i stället för kundfälten. När alla integrationer klarar version 2 byter du kontoinställningen så att webhooks följer med.

Resurs-ID:n

id-värdena på Subscription, Order och webhook-leveranser är heltal i produktion idag (t.ex. 76963688). Hantera dem som opaque identifiers 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- och kontakt-ID:n är heltal och kommer rimligtvis inte byta format. Konto-ID i URL-pathar är numeriska idag också; behandla dem också som opaque identifiers.

Paginering

List-endpoints returnerar data plus pagination. Använd ?page=2 för att bläddra vidare.

{
  "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" }
  }
}

Fel

Alla fel från https://app.octany.com/api/{account}/… kommer som JSON, oavsett vad du skickar i Accept. message är alltid på engelska. Bygg logiken på code, inte på message.

{
  "message": "Resource not found.",
  "code": "not_found",
  "docs_url": "https://build.octany.com/docs/integration.md#errors"
}

Status	code	Exempelmeddelande / kommentar
400	`bad_request`	Till exempel en `Octany-Version`-header som inte stöds: ”Unsupported Octany-Version header. Use one of: 1, 2.”
401	`unauthenticated`	”Missing or invalid X-API-KEY header.”
403	`forbidden`	”Your plan does not include API access.” Har också en äldre `error`-nyckel med samma text.
404	`not_found`	Okänd route: ”The route api/… could not be found.” Saknad post: ”Resource not found.”
405	`method_not_allowed`	t.ex. ”Product is not deletable”
422	`validation_failed`	Första valideringsmeddelandet, plus `errors` med en lista meddelanden per fält.
429	`rate_limited`	”Too Many Attempts.” Gränsen är 120 anrop per minut. Svaret skickar headers för `Retry-After`, `X-RateLimit-Limit` och `X-RateLimit-Remaining`.
5xx	`server_error`	”Server Error”
Övriga 4xx	`client_error`	t.ex. 402 när `POST /subscription/{id}/order` inte kunde dra beloppet.

Vissa endpoints skickar också äldre fält bredvid message, code och docs_url. De finns kvar för bakåtkompatibilitet, så ny kod kan ignorera dem:

{
  "message": "Not Found",
  "code": "not_found",
  "docs_url": "https://build.octany.com/docs/integration.md#errors",
  "status": 404,
  "success": false,
  "error": { "code": null, "message": null }
}

Några av de äldre felen svarar med HTTP 500 vid ogiltig input och får därför code: server_error. Ett exempel är en ogiltig eller redan registrerad webhook-URL. Läs message i det läget. Där står vad som var fel i anropet. Alla detaljer: integration.md#errors.

Discovery

GET https://app.octany.com/api kräver ingen API-nyckel. Svaret innehåller bas-URL:en, autentiseringen och länkar till den här dokumentationen:

{
  "name": "Octany API",
  "base_url": "https://app.octany.com/api/{account}",
  "auth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" },
  "docs_url": "https://build.octany.com/api",
  "openapi_url": "https://build.octany.com/docs/openapi.yaml",
  "llms_txt": "https://build.octany.com/llms.txt"
}

https://app.octany.com/openapi.yaml och https://app.octany.com/api/openapi.yaml gör en redirect (302) till OpenAPI-specen. https://app.octany.com/llms.txt pekar tillbaka hit.

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

GET/subscriptions

Listar prenumerationer. Stödjer page och filter[reference_id].

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

GET/subscription/{id}

Hämta en prenumeration via dess Octany-ID.

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

POST/subscription/{id}/cancel

Avsluta en prenumeration. Inga fler förnyelser görs. Beroende på produkten kan prenumerationen vara aktiv fram till ends_at.

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

POST/subscription/{id}/product

Byt produkten på en prenumeration.

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 }'

GET/subscription/{id}/orders

Lista ordrar för en prenumeration. Stödjer page, per_page, filter[product_id] och filter[state].

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

POST/subscription/{id}/order

Skapa en engångsorder på en befintlig prenumeration, debiterad via prenumerationens betalsätt.

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 #

GET/order/{id}

Hämta en order via dess Octany-ID. Ordrar exponerar totaler, moms, status, referensfält, leveranslänkar, metadata och egna fält.

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

Order-status

created confirmed payment_pending_user payment_pending payment_failed payment_cancelled payment_refunded paid

§ 04.4 Products #

GET/products

Lista produkter. Produktsvar innehåller pris, moms, intervall, lagerflaggor, bilder och visningssträngar.

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

GET/product/{id}

Hämta en produkt via numeriskt produkt-ID.

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

POST/product/{id}

Uppdatera en produkt. Bara skickade fält uppdateras.

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"
      }'

Värden för återkommande produkters interval är day, week, month, half-year och year. Produktens typ kan begränsa vilka intervall som är tillgängliga.

DELETE/product/{id}

Ta bort en produkt.

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

§ 04.5 Contacts #

Kontakter är personerna och företagen i kontots CRM. En kontakts type är person eller company, och en person kan höra till ett företag via parent_contact_id.

GET/contacts

Lista kontakter, 100 per sida, äldst först. Filtrera med type (person eller company), email (exakt matchning) eller q (delmatchning på namn, e-post eller telefon). Filtren följer med i pagineringslänkarna.

curl "https://app.octany.com/api/$ACCOUNT/contacts?email=anna%40example.com" \
  -H "X-API-KEY: $OCTANY_KEY"

GET/contacts/{id}

Hämta en kontakt med dess numeriska ID. Borttagna kontakter ger 404.

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

POST/contacts

Skapa en kontakt. Svarar 201 med den nya kontakten. type är obligatoriskt, och minst ett av name, email eller phone måste vara ifyllt.

curl -X POST "https://app.octany.com/api/$ACCOUNT/contacts" \
  -H "X-API-KEY: $OCTANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "person",
        "name": "Anna Persson",
        "email": "[email protected]",
        "phone": "070-123 45 67",
        "personal_identity_number": "19951027-2389",
        "parent_contact_id": 1001,
        "metadata": { "crm_id": "CRM-1001" },
        "address": {
          "line1": "Storgatan 1",
          "zip": "111 22",
          "city": "Stockholm",
          "country": "SE"
        }
      }'

PATCH/contacts/{id}

Uppdatera en kontakt. Bara fälten du skickar ändras; skicka null för att tömma ett fält. Fälten i address slås ihop med den befintliga adressen. Varje ändring sparas i kontaktens historik med källan ”API”. Nycklar i metadata slås ihop med befintlig metadata.

curl -X PATCH "https://app.octany.com/api/$ACCOUNT/contacts/1042" \
  -H "X-API-KEY: $OCTANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "address": { "city": "Göteborg" } }'

DELETE/contacts/{id}

Ta bort en kontakt. Den försvinner från API:et och kontaktlistan i admin, tillsammans med sina värden för egna fält.

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

Regler för kontakter

Identitetsnummer är unika. Ett personal_identity_number (personer) eller company_number (företag) som redan hör till en annan kontakt i kontot avvisas med 422. Formatet spelar ingen roll: 19951027-2389 och 199510272389 är samma nummer.
Skapa dedupliceras inte. POST /contacts skapar alltid en ny kontakt, även om en annan kontakt har samma e-post eller telefonnummer. Slå upp kontakten med GET /contacts?email=… först om du hellre vill uppdatera.
Värden normaliseras. Telefonnummer sparas i internationellt format (070-123 45 67 blir +46701234567) och svenska personnummer som 12 siffror.
parent_contact_id måste vara ett företag i samma konto.
Egna fält ingår inte i kontakt-API:et än.
Metadata sparar dina egna ID:n på en kontakt, till exempel postens ID i ditt CRM. Skicka det som ett objekt med strängvärden (högst 50 nycklar, 500 tecken var) i POST eller PATCH. Nycklarna du skickar slås ihop med befintlig metadata, och null tar bort en nyckel. Ändrar du bara metadata skickas inget contact.updated, så när du skriver tillbaka ditt ID startar ingen webhook-loop. I API-version 2 bäddar prenumerationer och ordrar in kontakten med sin metadata.
Webhooks. Välj opt-in-eventen contact.created, contact.updated och contact.deleted på en webhook-endpoint för att hålla din kopia i synk. Se kontaktevent.

Valideringsfel

Kontakt-endpoints returnerar alla valideringsfel, grupperade per fält, med status 422 och code: validation_failed. Meddelandena är alltid på engelska.

{
  "message": "The type field is required. (and 1 more error)",
  "code": "validation_failed",
  "docs_url": "https://build.octany.com/docs/integration.md#errors",
  "errors": {
    "type": ["The type field is required."],
    "name": ["At least one of name, email, or phone is required."]
  }
}

§ 04.6 Webhook-endpoints #

POST/webhooks/endpoints

Registrera en URL som ska ta emot signerade webhook-event. Endpoint-hemligheten genereras av Octany och hämtas från admin efter att endpointen skapats.

En ogiltig eller redan registrerad URL ger ett äldre fel med HTTP 500 och code: server_error. Läs message för att se vad som var fel. Se Fel.

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.7 Payload-form #

Exemplen för prenumeration och order följer versionen som är vald i headern. I version 2 bäddar de in givaren som contact.

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": {}
}

{
  "id": 76963688,
  "contact": {
    "id": 1042,
    "type": "person",
    "name": "Anna Persson",
    "email": "[email protected]",
    "metadata": { "crm_id": "CRM-1001" },
    /* … övriga kontaktfält */
  },
  "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",
  "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": {}
}

{
  "id": 516253755,
  "contact": {
    "id": 1042,
    "type": "person",
    "name": "Anna Persson",
    "email": "[email protected]",
    "metadata": { "crm_id": "CRM-1001" },
    /* … övriga kontaktfält */
  },
  "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
}

Contact

{
  "id": 1042,
  "type": "person",
  "name": "Anna Persson",
  "email": "[email protected]",
  "phone": "+46701234567",
  "personal_identity_number": "199510272389",
  "company_number": null,
  "parent_contact_id": 1001,
  "address": {
    "line1": "Storgatan 1",
    "line2": null,
    "zip": "111 22",
    "city": "Stockholm",
    "country": "SE"
  },
  "metadata": { "crm_id": "CRM-1001" },
  "first_seen_at": "2026-10-02T09:12:44.000000Z",
  "created_at": "2026-10-02T09:12:44.000000Z",
  "updated_at": "2026-10-02T09:12:44.000000Z"
}

address är null när kontakten saknar adress.

← Webhooks OpenAPI-spec →