# Goakal External API — LLM Reference

## Changelog
- 2026-10-07 (v1): Services now include visibility ("draft", "public", "unlisted" or "archived"). POST /services and PATCH /services/:cuid accept visibility ("public", "unlisted" or "archived"); GET /services accepts ?visibility= to filter.
- 2026-10-03 (v1): PATCH /services/:cuid/landing-data converts Markdown in deskripsi and courseDetail[].detail to the landing page HTML on save. See "Rich text format" under that endpoint.
- 2026-09-30 (v1): POST /services/:cuid/images refuses SVG images (VALIDATION_ERROR). Use JPEG, PNG, GIF or WebP.
- 2026-09-30 (v1): Added GET /services/:cuid/landing-data — read daftarPengajar and daftarDeskripsi. PATCH replaces each field it is sent, whole: read first, then send the full list.
- 2026-04-22 (v1): Added GET /services/:cuid/reviews — list published testimonials for a service. Added registration page prefill via query params (no API needed to create transactions — redirect users to the apply page instead).
- 2026-04-16 (v1): Services CRU responses now include url_link (format: https://goakal.com/{schoolUrlId}/{classUrlId}). Price scheme CRU responses now include url_link (format: https://goakal.com/{schoolUrlId}/{classUrlId}/{shortId}/apply). url_link is null when the school has no urlId configured.

---

## IMPORTANT WORKFLOW

To create a fully configured service with a price scheme:

1. POST /services — create the service (title, url_id, type required)
2. POST /services/:cuid/images — upload images; receive imageId and imageUrl per image
3. PATCH /services/:cuid — set media_gallery: [{ type: "image", mediaId, mediaUrl }, ...]
4. POST /benefits — create any benefits needed (or use existing benefit IDs)
5. POST /services/:cuid/price-schemes — create price scheme with benefits[] (at least one MESSAGE required)
6. GET /services/:cuid/landing-data, then PATCH /services/:cuid/landing-data with the full daftarPengajar / daftarDeskripsi lists
7. Optional: PATCH /services/:cuid with { "visibility": "public" } to show it on your organization page (a new service is "unlisted")
8. Optional: to sell an add-on at checkout, POST /benefits with type TEXT, then POST /services/:cuid/cross-sales with that id in benefitIds (at least one TEXT required)

---

## Authentication
All requests require header: X-Api-Key: <your_api_key>
Get an API key from: Dashboard > Developer > API Keys (select "Service API" scope)

## Base URL
https://goakal.com/service/api/v1

## MCP
The same API is available as an MCP server (Streamable HTTP) at https://goakal.com/service/mcp,
with the same X-Api-Key. Each tool calls one endpoint below. Docs: https://goakal.com/docs/developer/mcp

## Rate Limiting
100 requests per 60 seconds per school. Shared across all API keys for the same school. Returns 429 with Retry-After header when exceeded.

## Response Format

### Success (single resource)
{ "success": true, "data": { ... } }

### Success (list with pagination)
{ "success": true, "data": [...], "meta": { "page": 1, "pageSize": 20, "total": 100 } }

### Error
{ "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable description", "field": "field_name" } }

### createdFrom field
All resources include a createdFrom field. Value is "external-api" for resources created via this API, null for resources created through the dashboard.

## Error Codes
| Code | HTTP | Description |
|------|------|-------------|
| UNAUTHORIZED | 401 | Invalid or missing API key |
| FORBIDDEN | 403 | Valid key but wrong school |
| NOT_FOUND | 404 | Resource doesn't exist or not owned by your school |
| VALIDATION_ERROR | 400 | Invalid input (includes field name) |
| DUPLICATE_URL | 400 | url_id already taken in your school |
| DUPLICATE_BENEFIT | 409 | WA_INVITATION benefit with this URL already exists |
| DUPLICATE_PROMO_CODE | 400 | Promo code already exists for this class |
| UNSUPPORTED_OPERATION | 409 | Operation not allowed for this resource type |
| RATE_LIMITED | 429 | Too many requests |
| INTERNAL_ERROR | 500 | Server error |

## Quick Reference
GET    /services                                  List all services (paginated)
GET    /services/:cuid                            Get a single service
POST   /services                                  Create a service
PATCH  /services/:cuid                            Partially update a service
GET    /services/:cuid/landing-data               Read landing page data
PATCH  /services/:cuid/landing-data               Set landing page data (each field replaces its whole list)
GET    /services/:cuid/price-schemes              List price schemes for a service
POST   /services/:cuid/price-schemes              Create a price scheme (benefits required)
PATCH  /services/:cuid/price-schemes/:id          Update or toggle visibility of a price scheme
GET    /benefits                                  List benefits (optional ?serviceCuid= filter)
POST   /benefits                                  Create a benefit
PATCH  /benefits/:id                              Update a benefit
GET    /services/:cuid/cross-sales                List cross-sale offers (penawaran tambahan) of a service
POST   /services/:cuid/cross-sales                Add a cross-sale offer (TEXT benefit required)
PATCH  /services/:cuid/cross-sales/:id            Update or hide a cross-sale offer
GET    /services/:cuid/transactions               List transactions with optional filters
GET    /services/:cuid/promos                     List promos for a service
POST   /services/:cuid/promos                     Create a promo
GET    /services/:cuid/promos/:id                 Get a single promo
PATCH  /services/:cuid/promos/:id                 Update a promo
POST   /services/:cuid/images                     Upload an image for media gallery
GET    /services/:cuid/reviews                    List published testimonials for a service

NOTE: There is currently no API to create transactions directly. Instead, redirect your users to
the registration page and pass their data as query params to prefill the form. This helps them
register faster without re-typing their details.
  Registration page URL format: https://goakal.com/{your-organization}/{serviceUrlId}/{priceSchemeShortId}/apply
  Supported query params: name, email, phone
  Example: https://goakal.com/my-school/my-class/abc123/apply?name=John+Doe&email=john%40example.com&phone=6281234567890
  The form remains fully editable so users can correct or update any prefilled value.

---

## GET /services

List all services in your school with pagination.

### Query Params
page: number, optional, default: 1
pageSize: number, optional, default: 20, max: 50
visibility: string, optional, enum: ["draft","public","unlisted","archived"] — only services with this visibility

### Response 200
{
  "success": true,
  "data": [{ "cuid": "clxxx", "title": "My Event", "type": "event", "visibility": "unlisted", ... }],
  "meta": { "page": 1, "pageSize": 20, "total": 5 }
}

### curl Example
curl https://goakal.com/service/api/v1/services \
  -H "X-Api-Key: ak_..."

---

## GET /services/:cuid

Get a single service by cuid.

### Path Params
cuid: string — service CUID

### Response 200
{
  "success": true,
  "data": {
    "cuid": "clxxx", "title": "My Event", "url_id": "my-event",
    "type": "event", "description": "...",
    "media_gallery": [{ "type": "image", "mediaId": "abc123", "mediaUrl": "https://..." }],
    "eventStartAt": null, "eventEndAt": null, "eventScheduleType": null,
    "eventAddress": null, "eventGmapsLink": null, "eventTimezone": null,
    "visibility": "unlisted",
    "createdFrom": "external-api", "createdAt": "...", "updatedAt": "...",
    "url_link": "https://goakal.com/your-organization/my-event"
  }
}

visibility — where the service can be seen and bought:
  "public"   — on your organization page; open for registration
  "unlisted" — not on your organization page; open for registration through url_link
  "archived" — hidden; closed for registration
  "draft"    — not published yet (made in the Goakal dashboard); read only, publish it in the dashboard

### curl Example
curl https://goakal.com/service/api/v1/services/clxxx \
  -H "X-Api-Key: ak_..."

---

## POST /services

Create a new service.

### Request Body
title: string, required
url_id: string, required, regex /^[A-Za-z0-9-]+$/, unique within school
type: string, REQUIRED, enum: ["event","digital_product"]
  - "event" maps to DB type "default"; response always returns "event"
  - Other types (membership, donation) are NOT supported
description: string, optional — plain text summary under the title; line breaks kept, no Markdown or HTML
media_gallery: array, optional — items from POST /services/:cuid/images
  Format: [{ "type": "image", "mediaId": "abc123", "mediaUrl": "https://..." }]
eventStartAt: string, optional, ISO 8601 — ONLY allowed when type is "event"; VALIDATION_ERROR if type is "digital_product"
eventEndAt: string, optional, ISO 8601 — ONLY allowed when type is "event"; VALIDATION_ERROR if type is "digital_product"
eventAddress: string, optional (event type only)
eventGmapsLink: string, optional
eventTimezone: string, optional, IANA timezone e.g. "Asia/Jakarta" — ONLY allowed when type is "event"; VALIDATION_ERROR if type is "digital_product"
visibility: string, optional, enum: ["public","unlisted","archived"], default: "unlisted" — see GET /services/:cuid

NOTE: main_image → VALIDATION_ERROR. Use media_gallery instead.
NOTE: landingData → VALIDATION_ERROR. Use PATCH /services/:cuid/landing-data instead.

### Response 201
{
  "success": true,
  "data": {
    "cuid": "clxxx", "title": "My Event", "url_id": "my-event",
    "type": "event", "description": "...", "media_gallery": [],
    "eventStartAt": null, "eventEndAt": null, "eventScheduleType": null,
    "eventAddress": null, "eventGmapsLink": null, "eventTimezone": null,
    "visibility": "unlisted",
    "createdFrom": "external-api", "createdAt": "...", "updatedAt": "...",
    "url_link": "https://goakal.com/your-organization/my-event"
  }
}

### Error Cases
VALIDATION_ERROR — missing/invalid field
DUPLICATE_URL — url_id already exists in this school

### curl Example
curl -X POST https://goakal.com/service/api/v1/services \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"My Event","url_id":"my-event","type":"event"}'

---

## PATCH /services/:cuid

Partial update. Only provided fields are changed.

### Path Params
cuid: string — service CUID

### Request Body (all optional)
title: string
url_id: string, must be unique
description: string — plain text, see POST /services
media_gallery: array — replaces current gallery; removed images are deleted from storage
  Format: [{ "type": "image", "mediaId": "abc123", "mediaUrl": "https://..." }]
eventStartAt: string, ISO 8601 — ONLY allowed when effective service type is "event"
eventEndAt: string, ISO 8601 — ONLY allowed when effective service type is "event"
eventAddress: string — ONLY allowed when effective service type is "event"
eventTimezone: string, IANA timezone — ONLY allowed when effective service type is "event"
eventGmapsLink: string
visibility: string, enum: ["public","unlisted","archived"] — see GET /services/:cuid. A new value cancels any automatic visibility change scheduled in the dashboard; the current value changes nothing.
  On a "draft" service → UNSUPPORTED_OPERATION (409); publish it in the Goakal dashboard first.
  visibilityType → VALIDATION_ERROR. Use visibility.

NOTE: "Effective type" = the new type if provided in this request, else the existing type. Sending event-only fields alongside type:"digital_product", or on a service already of type digital_product → VALIDATION_ERROR.
NOTE: main_image or landingData → VALIDATION_ERROR.

### Response 200
{ "success": true, "data": { cuid, title, url_id, type, description, media_gallery, eventStartAt, eventEndAt, eventScheduleType, eventAddress, eventGmapsLink, eventTimezone, visibility, createdFrom, createdAt, updatedAt, url_link } }

url_link format: https://goakal.com/{schoolUrlId}/{classUrlId} — null if school has no urlId

### curl Example
curl -X PATCH https://goakal.com/service/api/v1/services/clxxx \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"media_gallery":[{"type":"image","mediaId":"abc123","mediaUrl":"https://..."}]}'

---

## GET /services/:cuid/landing-data

Read the landing data an integration can set.

### Response 200
{ "success": true, "data": { "cuid": "clxxx", "landingData": { "daftarPengajar": [...], "daftarDeskripsi": [...] }, "updatedAt": "..." } }

### curl Example
curl https://goakal.com/service/api/v1/services/clxxx/landing-data \
  -H "X-Api-Key: ak_..."

---

## PATCH /services/:cuid/landing-data

Set top-level fields of landingData. Each field you send REPLACES that whole field — sending
daftarDeskripsi replaces the whole block list, it does not append. Fields you do not send are kept.
To add or change one block: GET /services/:cuid/landing-data, change the list, PATCH the full list.
Unknown fields are rejected.

### Path Params
cuid: string — service CUID

### Request Body (all optional; merged into existing data)
optionalSectionVisibility: object, { "DESKRIPSI": boolean } — DEPRECATED. Still accepted so older
  integrations keep working, but it is ignored and stripped before saving. It has no effect on the
  landing page. Do not send it in new integrations.
daftarPengajar: array of instructor objects:
  [{ "foto": { "imageUrl": string, "imageId": string }, "nama": string, "title": string }]
daftarDeskripsi: array of description or testimonial blocks:
  deskripsi item: { "type": "deskripsi", "title": string, "deskripsi": string, "courseDetail": [{ "title": string, "detail": string }] }
  testimonial item: { "type": "testimonial", "title": string, "daftarTestimonial": [{ "photo": { "imageUrl", "imageId" }, "name", "role", "description", "gallery": { "imageUrl", "imageId" } }] }

Any other field → VALIDATION_ERROR

### Rich text format (deskripsi, courseDetail[].detail)
These two fields are rich text. The landing page shows them as HTML. Send either:
- Markdown — converted to HTML on save. One list item per line: "1. " numbered, "- " bullet,
  indent a sub-item by 2 spaces. **bold**, *italic*, [link](https://...), "## " heading.
  Leave a blank line between paragraphs; a single line break starts a new line.
- HTML — kept as sent. Use <p>, <strong>, <em>, <u>, <a>, <ol>/<ul> with <li>, <h2>, <h3>. One <p> per line;
  <p><br></p> for an empty line. Nest list items with <li class="ql-indent-1"> in a flat list, not a nested <ol>.
Never put several list items in one line ("1. A 2. B 3. C"): it shows as one paragraph.
All other text fields (title, nama, name, role, testimonial description) are plain text.

Example deskripsi (Markdown, as a JSON string):
"Di kelas ini kamu belajar:\n\n1. Dasar HTML\n2. CSS **flexbox**\n   - grid\n3. JavaScript"
Stored as:
"<p>Di kelas ini kamu belajar:</p><p><br></p><ol><li>Dasar HTML</li><li>CSS <strong>flexbox</strong></li><li class=\"ql-indent-1\">grid</li><li>JavaScript</li></ol>"

### Response 200
{ "success": true, "data": { "cuid": "clxxx", "landingData": { ...merged... }, "updatedAt": "..." } }

### curl Example
curl -X PATCH https://goakal.com/service/api/v1/services/clxxx/landing-data \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"daftarPengajar":[{"foto":{"imageUrl":"https://...","imageId":"abc"},"nama":"Budi","title":"Senior Dev"}]}'

---

## GET /services/:cuid/price-schemes

List all price schemes for a service, including linked benefits.

### Response 200
{ "success": true, "data": [ { "cuid": "clyyy", "title": "Early Bird", "mainAmount": 500000, "currency": "IDR", "type": "fixedAmount", "order": 0, "checklistDescription": [], "minimumOpenAmount": null, "isFirstPaymentEndDateEnabled": false, "firstPaymentEndDate": null, "openingDate": null, "isPriceShownBeforeOpening": true, "isShow": true, "isQuotaEnabled": false, "quotaMax": 0, "createdFrom": "external-api", "createdAt": "...", "updatedAt": "...", "url_link": "https://goakal.com/your-organization/my-event/abc123/apply" } ] }

url_link format: https://goakal.com/{your-organization}/{serviceUrlId}/{priceSchemeShortId}/apply — null if school has no urlId

### curl Example
curl https://goakal.com/service/api/v1/services/clxxx/price-schemes \
  -H "X-Api-Key: ak_..."

---

## POST /services/:cuid/price-schemes

Create a price scheme. Only allowed for services of type event or digital_product.
At least one MESSAGE benefit is required. Benefits can be created inline or referenced by ID.

### Request Body
title: string, required
mainAmount: number, required, must be >= 0
currency: string, optional, enum: ["IDR","USD"], default: "IDR"
type: string, required, enum: ["openAmount","fixedAmount"]
  - "openAmount" → stored as "payAsYouWish"
  - "fixedAmount" → stored as "fixedAmount"
minimumOpenAmount: number, required when type=openAmount; must NOT be sent for fixedAmount; must be >= 0
order: number, optional, display order, default: 0
checklistDescription: string[], optional
isFirstPaymentEndDateEnabled: boolean, optional
firstPaymentEndDate: string, optional, ISO-8601 with timezone e.g. "2026-05-01T23:59:59+07:00"
openingDate: string, optional, ISO-8601 with timezone e.g. "2026-04-20T09:00:00+07:00"
  - before it, the landing page shows "Belum dibuka" with a live countdown and checkout refuses this price scheme
  - must be before firstPaymentEndDate when a deadline is set
isPriceShownBeforeOpening: boolean, optional, default: true — false hides the price on the landing page until openingDate
isShow: boolean, optional, default: true
isQuotaEnabled: boolean, optional
quotaMax: number, optional, must be >= 0
benefits: array, REQUIRED — must contain at least one MESSAGE benefit
  New benefit: { "type": "MESSAGE"|"WA_INVITATION", "details": { ... } }
  Existing benefit: { "id": 123 }
  MESSAGE details: { "title": string, "sender_name": string, "message": string }
  WA_INVITATION details: { "title": string, "invitation_url": string }

NOTE: isInstallmentEnabled, installmentPeriods, monthlyInstallmentDate → VALIDATION_ERROR if sent.

### Response 201
{
  "success": true,
  "data": {
    "cuid": "clyyy", "title": "Early Bird", "mainAmount": 500000,
    "currency": "IDR", "type": "fixedAmount", "order": 0,
    "checklistDescription": [], "minimumOpenAmount": null,
    "isFirstPaymentEndDateEnabled": false, "firstPaymentEndDate": null,
    "openingDate": null, "isPriceShownBeforeOpening": true,
    "isShow": true, "isQuotaEnabled": false, "quotaMax": 100,
    "createdFrom": "external-api", "createdAt": "...", "updatedAt": "...",
    "url_link": "https://goakal.com/your-organization/my-event/abc123/apply"
  }
}

### Error Cases
UNSUPPORTED_OPERATION (409) — service type is not event or digital_product
VALIDATION_ERROR — benefits missing, no MESSAGE benefit, inline benefit creation failed, removed field sent, or openingDate invalid or not before firstPaymentEndDate

### curl Example
curl -X POST https://goakal.com/service/api/v1/services/clxxx/price-schemes \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Early Bird","mainAmount":500000,"type":"fixedAmount","benefits":[{"type":"MESSAGE","details":{"title":"Welcome","sender_name":"Team","message":"Thank you for joining!"}}]}'

---

## PATCH /services/:cuid/price-schemes/:id

Update a price scheme. Use isShow to show/hide it from students.
The price scheme must belong to the service identified by :cuid — returns 404 otherwise.

### Path Params
cuid: string — service CUID
id: string — price scheme CUID

### Request Body (all optional)
title, mainAmount, currency, order, checklistDescription, isFirstPaymentEndDateEnabled, firstPaymentEndDate, openingDate, isPriceShownBeforeOpening, isShow, isQuotaEnabled, quotaMax

NOTE: openingDate — null or "" removes it. It must be before firstPaymentEndDate; when the request does not send a deadline, the stored one is used for this check.

NOTE: quotaUsed is read-only and system-managed. Sending it → VALIDATION_ERROR.
NOTE: isInstallmentEnabled, installmentPeriods, monthlyInstallmentDate → VALIDATION_ERROR if sent.

### Response 200
{ "success": true, "data": { cuid, title, mainAmount, currency, type, order, checklistDescription, minimumOpenAmount, isFirstPaymentEndDateEnabled, firstPaymentEndDate, openingDate, isPriceShownBeforeOpening, isShow, isQuotaEnabled, quotaMax, createdFrom, createdAt, updatedAt, url_link } }

url_link format: https://goakal.com/{your-organization}/{serviceUrlId}/{priceSchemeShortId}/apply — null if school has no urlId

### Error Cases
NOT_FOUND (404) — service not found, or price scheme doesn't belong to this service
VALIDATION_ERROR — quotaUsed sent, installment field sent, or invalid value
PROMO_DISCOUNT_CONFLICT (409) — mainAmount lowered below a promo discount already applied to this price scheme.
  The response carries `conflicts: [{ promoId, promoCode, discountAmount }]`. Lower those discounts first.

### curl Example (hide price scheme)
curl -X PATCH https://goakal.com/service/api/v1/services/clxxx/price-schemes/clyyy \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"isShow":false}'

---

## GET /benefits

List all benefits for your school. Optionally filter to benefits linked to a specific service's price schemes or cross-sale offers.

### Query Params
serviceCuid: string, optional — return only benefits linked to price schemes or cross-sale offers of this service

### Response 200
{ "success": true, "data": [ { "id": 1, "type": "WA_INVITATION", "details": { "title": "Group A", "invitation_url": "https://chat.whatsapp.com/..." }, "createdFrom": "external-api", "createdAt": "...", "updatedAt": "..." } ] }

### curl Examples
# All school benefits:
curl https://goakal.com/service/api/v1/benefits \
  -H "X-Api-Key: ak_..."

# Benefits linked to a specific service:
curl "https://goakal.com/service/api/v1/benefits?serviceCuid=clxxx" \
  -H "X-Api-Key: ak_..."

---

## POST /benefits

Create a new benefit. Only MESSAGE, WA_INVITATION and TEXT types are supported.
MESSAGE is for price schemes. TEXT is the message a cross-sale offer delivers.

### Request Body
type: string, required, enum: ["MESSAGE","WA_INVITATION","TEXT"]
details: object, required

MESSAGE details:
  title: string, required
  sender_name: string, required
  message: string, required

WA_INVITATION details:
  title: string, required
  invitation_url: string, required, must be https://chat.whatsapp.com/...

TEXT details:
  title: string, required
  message: string, required — HTML or plain text, shown to the buyer after payment

### Response 201
{ "success": true, "data": { "id": 1, "type": "MESSAGE", "details": { ... }, "createdFrom": "external-api", "createdAt": "...", "updatedAt": "..." } }

### Error Cases
DUPLICATE_BENEFIT (409) — WA_INVITATION with this URL already exists for your school
VALIDATION_ERROR — unsupported type or invalid details

### curl Example
curl -X POST https://goakal.com/service/api/v1/benefits \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"type":"MESSAGE","details":{"title":"Welcome","sender_name":"Team","message":"Thank you for joining!"}}'

---

## PATCH /benefits/:id

Update a benefit.

### Path Params
id: string — benefit ID (integer as string)

### Request Body
type: string, required, enum: ["MESSAGE","WA_INVITATION","TEXT"]
details: object, required

### Response 200
{
  "success": true,
  "data": {
    "id": 1, "type": "MESSAGE", "details": { ... },
    "createdFrom": "external-api", "createdAt": "...", "updatedAt": "...",
    "impactedPriceSchemes": [{ "cuid": "clyyy", "title": "Early Bird" }]
  }
}

WARNING: impactedPriceSchemes lists price schemes currently using this benefit. Updating affects all linked price schemes immediately.

### curl Example
curl -X PATCH https://goakal.com/service/api/v1/benefits/1 \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"type":"MESSAGE","details":{"title":"Updated Welcome","sender_name":"Team","message":"Hello!"}}'

---

## GET /services/:cuid/cross-sales

List the cross-sale offers (penawaran tambahan) of a service, in checkout order. A cross-sale offer is an
add-on the buyer can tick at checkout, next to the price scheme.

### Response 200
{ "success": true, "data": [ { "id": 12, "title": "Bonus ebook", "description": null, "mainAmount": 50000, "initialAmount": 100000, "order": 0, "isShow": true, "benefitIds": [3, 7] } ] }

### curl Example
curl https://goakal.com/service/api/v1/services/clxxx/cross-sales \
  -H "X-Api-Key: ak_..."

---

## POST /services/:cuid/cross-sales

Add a cross-sale offer at the end of the service's list.

### Request Body
title: string, required
mainAmount: number, required — whole number, 0 to 1000000000
benefitIds: number[], required — must include at least one TEXT benefit (create one with POST /benefits),
  unless isShow is false: a hidden offer needs none.
  Allowed benefit types: TEXT, WA_INVITATION, FILE, WEBINAR, LMS_ACCESS. Benefits must belong to your organization.
description: string | null, optional
initialAmount: number | null, optional — original price, shown struck through, 0 to 1000000000
isShow: boolean, optional, default true
Unknown fields are refused.

### Response 201
{ "success": true, "data": { "id": 12, "title": "Bonus ebook", ..., "benefitIds": [3] } }

### Error Cases
VALIDATION_ERROR (400) — no TEXT benefit, benefit not found or not owned, benefit type an offer cannot deliver, or invalid field
NOT_FOUND (404) — service not found
CONFLICT (409) — the offers changed during the request; retry

### curl Example
curl -X POST https://goakal.com/service/api/v1/services/clxxx/cross-sales \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Bonus ebook","mainAmount":50000,"benefitIds":[3]}'

---

## PATCH /services/:cuid/cross-sales/:id

Change a cross-sale offer. Send only the fields to change; the others keep their values.
benefitIds, when sent, replaces the whole set (a benefit absent from it is switched off) and is checked
for ownership and type. A visible offer must still have a TEXT benefit after the change; a hidden one
(isShow: false) needs none, so any offer can be hidden as it is. There is no delete: purchases point at
an offer.

### Request Body
Same fields as POST, all optional.

### Error Cases
Same as POST. NOT_FOUND (404) also when the offer is not an offer of this service.

### curl Example
curl -X PATCH https://goakal.com/service/api/v1/services/clxxx/cross-sales/12 \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"isShow":false}'

---

## GET /services/:cuid/transactions

List transactions for a service with optional filtering and pagination.

### Query Params
status: string, optional, enum: ["PAID","SETTLED","PENDING","EXPIRED","FAILED"]
priceSchemeTitle: string, optional, partial match
page: number, optional, default: 1
pageSize: number, optional, default: 20, max: 100
_schema: "true", optional — returns field descriptions instead of data

### Response Fields
paymentId: string — payment gateway ID
incomingAmount: number — amount paid by buyer
payerName: string — buyer name
payerEmail: string — buyer email, normalised (lower case; Gmail without dots)
payerRawEmail: string — buyer email as the buyer typed it (dots kept); use this to show or contact
payerPhoneNumber: string — buyer phone number
packages: any — package data attached to the transaction
status: string — PAID | SETTLED | PENDING | EXPIRED | FAILED
createdAt: string — ISO 8601
updatedAt: string — ISO 8601
paidAt: string | null — ISO 8601, set when payment is confirmed
expiryDate: string | null — ISO 8601, when the payment link expires
promoCode: string | null — promo code applied at checkout
serviceCuid: string — cuid of the service
serviceTitle: string — title of the service
priceSchemeCuid: string — cuid of the price scheme used
priceSchemeTitle: string — title of the price scheme
referralCode: string | null — referral code used at checkout
invoiceUrl: string | null — payment invoice URL (ONLY present when status is PENDING)

NOTE: Internal financial fields (akalFee, paymentFee) and registration/submission fields are intentionally excluded.

### Response 200
{
  "success": true,
  "data": [{
    "paymentId": "AKL-izhj8nv",
    "incomingAmount": 500000,
    "payerName": "John Doe",
    "payerEmail": "john@example.com",
    "payerPhoneNumber": "6281234567890",
    "packages": "",
    "status": "PAID",
    "createdAt": "2026-04-16T02:43:31.686Z",
    "updatedAt": "2026-04-16T02:44:19.326Z",
    "paidAt": "2026-04-16T02:44:00.000Z",
    "expiryDate": "2026-04-18T02:43:31.551Z",
    "promoCode": null,
    "serviceCuid": "cmnzo2f2j0002h1u28gax4eo2",
    "serviceTitle": "My Event",
    "priceSchemeCuid": "cmnzvxci40005h1qvuzdc18l3",
    "priceSchemeTitle": "Early Bird",
    "referralCode": null
  }],
  "meta": { "page": 1, "pageSize": 20, "total": 45 }
}

// When status is PENDING, invoiceUrl is also included:
{
  ...,
  "status": "PENDING",
  "invoiceUrl": "https://..."
}

### curl Example
curl "https://goakal.com/service/api/v1/services/clxxx/transactions?status=PAID&page=1" \
  -H "X-Api-Key: ak_..."

---

## GET /services/:cuid/promos

List all promos for a service.

### Response 200
{
  "success": true,
  "data": [{
    "id": 1, "title": "Launch Promo", "promo_code": "launch50",
    "isLimited": true, "quota": 100, "time_start": null,
    "time_end": "2025-12-31T23:59:59.000Z", "notes": "Launch discount",
    "discounts": [{ "priceSchemeCuid": "clyyy", "discountAmount": 50000 }],
    "promoLink": "https://goakal.com/school-url/class-url?promo=launch50",
    "createdFrom": "external-api", "createdAt": "...", "updatedAt": "..."
  }]
}

### curl Example
curl https://goakal.com/service/api/v1/services/clxxx/promos \
  -H "X-Api-Key: ak_..."

---

## POST /services/:cuid/promos

Create a promo code for a service.

### Request Body
title: string, required
promo_code: string, required, stored lowercase, unique per service
isLimited: boolean, optional, default: false
quota: number, optional, max uses when isLimited is true
time_start: string, optional, ISO 8601
time_end: string, optional, ISO 8601
notes: string, optional
discounts: array, optional, [{ "priceSchemeCuid": "clyyy", "discountAmount": 50000 }]
  IMPORTANT: each priceSchemeCuid must belong to the service identified by :cuid — VALIDATION_ERROR otherwise
  discountAmount must be >= 0 and must not exceed that price scheme's mainAmount — a promo can never
  make the total payable negative. openAmount price schemes are exempt from the upper bound, since the
  buyer names the amount at checkout; a discount naming one is dropped rather than stored.

### Response 201
{ "success": true, "data": { "id": 1, "title": "Launch Promo", "promo_code": "launch50", "promoLink": "https://goakal.com/school-url/class-url?promo=launch50", "createdFrom": "external-api", ... } }

### Error Cases
DUPLICATE_PROMO_CODE (400) — promo code already exists for this service
VALIDATION_ERROR — priceSchemeCuid in discounts doesn't belong to this service

### curl Example
curl -X POST https://goakal.com/service/api/v1/services/clxxx/promos \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Launch Promo","promo_code":"LAUNCH50","isLimited":true,"quota":100}'

---

## GET /services/:cuid/promos/:id

Get a single promo by ID.

### Response 200
{ "success": true, "data": { "id": 1, "title": "Launch Promo", "promo_code": "launch50", "promoLink": "https://goakal.com/school-url/class-url?promo=launch50", "createdFrom": "external-api", ... } }

### curl Example
curl https://goakal.com/service/api/v1/services/clxxx/promos/1 \
  -H "X-Api-Key: ak_..."

---

## PATCH /services/:cuid/promos/:id

Update a promo. All fields optional.

### Request Body (all optional)
title, promo_code (stored lowercase, unique per service), isLimited, quota, time_start (ISO 8601), time_end (ISO 8601), notes
discounts: array, optional, [{ "priceSchemeCuid": "clyyy", "discountAmount": 50000 }]
  IMPORTANT: each priceSchemeCuid must belong to the service identified by :cuid — VALIDATION_ERROR otherwise
  discountAmount must be >= 0 and must not exceed that price scheme's mainAmount — a promo can never
  make the total payable negative. openAmount price schemes are exempt from the upper bound, since the
  buyer names the amount at checkout; a discount naming one is dropped rather than stored.

### Error Cases
DUPLICATE_PROMO_CODE (400) — code already taken by another promo in this service
VALIDATION_ERROR — priceSchemeCuid in discounts doesn't belong to this service

### Response 200
{ "success": true, "data": { id, title, promo_code, isLimited, quota, time_start, time_end, notes, discounts, promoLink, createdFrom, createdAt, updatedAt } }

### curl Example
curl -X PATCH https://goakal.com/service/api/v1/services/clxxx/promos/1 \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"quota":200}'

---

## POST /services/:cuid/images

Upload an image for the landing page media gallery.

### Request
Content-Type: multipart/form-data
Form field: file — required, image/* types only, max 10MB (JPEG, PNG, GIF, WebP). SVG is refused (VALIDATION_ERROR).

### Response 201
{ "success": true, "data": { "imageId": "abc123", "imageUrl": "https://...", "fileName": "thumbnail.jpg", "contentType": "image/jpeg", "size": 204800 } }

### Workflow
1. Upload image → receive imageId and imageUrl
2. Use them in PATCH /services/:cuid:
   { "media_gallery": [{ "type": "image", "mediaId": "<imageId>", "mediaUrl": "<imageUrl>" }] }
   When media_gallery is updated, images removed from the array are automatically deleted from storage.

### curl Example
curl -X POST https://goakal.com/service/api/v1/services/clxxx/images \
  -H "X-Api-Key: ak_..." \
  -F "file=@thumbnail.jpg"

---

## GET /services/:cuid/reviews

List published testimonials for a service. Only reviews that have been submitted with testimonial text are returned. Results are ordered by most recent first.

### Path Params
cuid: string — service CUID

### Query Params
page: number, optional, default: 1
pageSize: number, optional, default: 20, max: 100

### Response Fields
id: string — review ID
testimonialName: string — name displayed on the testimonial
testimonialRole: string | null — role/title shown under the name
testimonialPhotoUrl: string | null — URL of the attendee's photo
testimonialRating: number | null — rating (1–5) if provided
testimonialText: string — testimonial body (guaranteed non-null in this endpoint)
submittedAt: string — ISO 8601, when the testimonial was submitted

### Response 200
{
  "success": true,
  "data": [{
    "id": "clrev123",
    "testimonialName": "Jane Doe",
    "testimonialRole": "Designer",
    "testimonialPhotoUrl": "https://...",
    "testimonialRating": 5,
    "testimonialText": "Amazing experience, highly recommended!",
    "submittedAt": "2026-04-10T09:21:00.000Z"
  }],
  "meta": { "page": 1, "pageSize": 20, "total": 12 }
}

### Error Cases
NOT_FOUND (404) — service not found or not owned by your organization

### curl Example
curl "https://goakal.com/service/api/v1/services/clxxx/reviews?page=1&pageSize=20" \
  -H "X-Api-Key: ak_..."
