@occassionly/partner-sdk

Official SDK for the Occassionly Partner API.

Install

npm i @occassionly/partner-sdk

For builds published automatically from branch ft/partner:

npm i @occassionly/partner-sdk@ft-partner

Usage

import { createClient } from "@occassionly/partner-sdk";

const client = createClient({
  partnerId: process.env.OCC_PARTNER_ID!,
  apiKeyId: process.env.OCC_API_KEY_ID!,
  apiSecret: process.env.OCC_API_SECRET!,
});

const credits = await client.getCredits();

baseUrl is optional and defaults to https://api.occassionly.com/api. If you override it, use only protocol + host (and optional port), for example: http://10.136.40.83:5000 (not .../api).

Methods

• getCredits()
• listEvents(params?)
• getEvent(partnerEventId)
• listEventCards(partnerEventId, params?)
• listActivities(params?)
• createEvent(payload)
• issueCard(payload)
• issueCardsBulk(payload)
• revokeCard(occCardId, payload?)
• approveCard(occCardId)
• verify(payload)
• verifyCardByQrPayload(qrPayload)
• verifyPublicCardByQrPayload(qrPayload)
• verifyCardByAccessCode(code)
• listWebhookOutbox(params?)
• retryDueWebhooks()
• replayWebhook(webhookEventId)

Helper utilities

• extractPartnerQrPayload(raw)
• isPartnerQrPayload(raw)
• normalizeGuestAccessCode(raw)
• isGuestAccessCode(raw)

Payloads and sample responses

getCredits()

Response:

{
  "partner_id": "partner_demo",
  "credits_total": 500,
  "credits_used": 120,
  "credits_remaining": 380,
  "credit_rules": {
    "issue_card": 1,
    "reapprove_card": 1,
    "revoke_card": 0,
    "verify_card": 0,
    "email_send": 1
  }
}

createEvent(payload)

Payload:

{
  "partner_event_id": "evt_12345",
  "event_name": "Wedding Reception",
  "start_at": "2026-03-28T13:00:00.000Z",
  "end_at": "2026-03-28T18:00:00.000Z",
  "timezone": "Africa/Lagos",
  "template": { "theme": "classic" }
}

listEvents(params?)

Response:

{
  "items": [
    {
      "partner_event_id": "evt_12345",
      "occ_event_id": "67f0f7c2e7f8f92b4d0e0c11",
      "event_name": "Wedding Reception",
      "status": "active",
      "cards_issued": 42,
      "cards_revoked": 1
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

Response:

{
  "occ_event_id": "67f0f7c2e7f8f92b4d0e0c11",
  "status": "active"
}

issueCard(payload)

Payload:

{
  "issue_ref": "evt_12345_guest_001",
  "partner_event_id": "evt_12345",
  "partner_guest_id": "guest_001",
  "guest_name": "Ibrahim Musa",
  "email": "[email protected]"
}

Response:

{
  "occ_card_id": "occ_card_ab12cd34",
  "status": "issued",
  "card_url": "https://occassionly.com/c/occ_card_ab12cd34",
  "qr_payload": "OCCP|occ_card_ab12cd34|ea73...",
  "email_delivery": "sent"
}

email_delivery can be sent, failed, or disabled.

issueCardsBulk(payload)

Payload:

{
  "items": [
    {
      "issue_ref": "evt_12345_guest_001",
      "partner_event_id": "evt_12345",
      "partner_guest_id": "guest_001",
      "guest_name": "Ibrahim Musa",
      "email": "[email protected]"
    },
    {
      "issue_ref": "evt_12345_guest_002",
      "partner_event_id": "evt_12345",
      "partner_guest_id": "guest_002",
      "guest_name": "Aisha Bello",
      "email": "[email protected]"
    }
  ]
}

Response:

{
  "total": 2,
  "created": 2,
  "idempotent": 0,
  "failed": 0,
  "results": []
}

verify(payload)

Payload:

{
  "qr_payload": "OCCP|occ_card_ab12cd34|ea73..."
}

Response:

{
  "status": "valid",
  "occ_card_id": "occ_card_ab12cd34"
}

Other status values: invalid, already_verified, revoked.

verifyCardByQrPayload(qrPayload)

const result = await client.verifyCardByQrPayload("OCCP2|...");

verifyPublicCardByQrPayload(qrPayload)

const result = await client.verifyPublicCardByQrPayload("OCCP2|...");

verifyCardByAccessCode(code)

const result = await client.verifyCardByAccessCode("GA-1A2B3C");

Accepted formats include GA-1A2B3C, GA1A2B3C, ga-1a2b3.

revokeCard(occCardId, payload?)

Payload:

{
  "reason": "manual_revoke"
}

approveCard(occCardId)

Response:

{
  "occ_card_id": "occ_card_ab12cd34",
  "status": "issued"
}

Response:

{
  "occ_card_id": "occ_card_ab12cd34",
  "status": "revoked"
}

listWebhookOutbox(params?)

Query params:

• status: pending | failed | dead_letter | delivered
• event_type: string
• limit: number
• cursor: string

Response:

{
  "items": [
    {
      "webhook_event_id": "4f9a...",
      "event_type": "card.issued",
      "status": "delivered"
    }
  ],
  "next_cursor": null
}

retryDueWebhooks()

Response:

{
  "scanned": 10,
  "retried": 3
}

replayWebhook(webhookEventId)

Response:

{
  "replayed": true
}

Common error response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Partner credit balance exhausted.",
    "details": null
  }
}