Authentication
All requests must include the X-Api-Key header. Create an API key from your dashboard under Developer → API Keys with the external_api scope.
X-Api-Key: ak_your_api_key_here
Base URL
https://goakal.com/service/api/v1Rate Limiting
100 requests per 60 seconds per organization — shared across all API keys belonging to the same organization. Returns 429 with Retry-After header.
Error Response Format
{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "url_id is required", "field": "url_id" } }Services
Image & landing data workflow
- POST /services — create the service
- POST /services/:cuid/images — upload each image; receive
imageIdandimageUrl - PATCH /services/:cuid — set
media_gallery: [{ type: "image", mediaId, mediaUrl }] - GET /services/:cuid/landing-data — read the current blocks, then PATCH /services/:cuid/landing-data with the full lists
Visibility
Every service has a visibility. You can set the first three; a new service is unlisted unless you send one.
public— on your organization page; open for registrationunlisted— not on your organization page; open for registration through its linkarchived— hidden; closed for registrationdraft— not published yet (made in the dashboard); read only, publish it in the dashboard
/servicesList all services in your organization with pagination.
Request Body
// Query params: page=1 // optional, default: 1 pageSize=20 // optional, default: 20, max: 50 visibility=public // optional: draft | public | unlisted | archived
Response
// 200 OK
{
"success": true,
"data": [{ "cuid": "clxxx", "title": "My Event", "type": "event", "visibility": "unlisted", ... }],
"meta": { "page": 1, "pageSize": 20, "total": 5 }
}Example
curl https://goakal.com/service/api/v1/services \ -H "X-Api-Key: ak_..."
/services/:cuidGet a single service by cuid.
Response
// 200 OK
{
"success": true,
"data": {
"cuid": "clxxx", "title": "My Event", "url_id": "my-event",
"type": "event", "description": "...",
"media_gallery": [{ "type": "image", "mediaId": "abc", "mediaUrl": "https://..." }],
"eventStartAt": null, "eventEndAt": null, "eventTimezone": null,
"visibility": "unlisted",
"createdFrom": "external-api", "createdAt": "...", "updatedAt": "...",
"url_link": "https://goakal.com/your-organization/my-event"
}
}Example
curl https://goakal.com/service/api/v1/services/clxxx \ -H "X-Api-Key: ak_..."
/servicesCreate a new service in your organization.
Request Body
{
"title": "My Event", // required
"url_id": "my-event", // required, alphanumeric + hyphens, unique
"type": "event", // REQUIRED: event | digital_product
"description": "...", // optional
"media_gallery": [ // optional — items from POST /services/:cuid/images
{ "type": "image", "mediaId": "abc123", "mediaUrl": "https://..." }
],
"visibility": "unlisted", // optional: public | unlisted | archived, default: unlisted
// Only accepted when type is "event" — VALIDATION_ERROR if type is "digital_product":
"eventStartAt": "2026-05-01T09:00:00+07:00", // optional, ISO 8601
"eventEndAt": "2026-05-01T17:00:00+07:00", // optional, ISO 8601
"eventAddress": "Jakarta Convention Center", // optional
"eventTimezone": "Asia/Jakarta" // optional, IANA timezone
}Response
// 201 Created
{
"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"
}
}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"}'Error Codes
VALIDATION_ERROR— Missing required field, invalid format, event-only field sent for digital_product, or unsupported field (main_image / landingData)DUPLICATE_URL— url_id already exists in your organization/services/:cuidPartially update a service. Only provided fields are changed. Event-only fields (eventStartAt, eventEndAt, eventTimezone) are rejected when the effective type is not 'event' — effective type is the new type if provided in this request, otherwise the current type.
Request Body
{
"title": "Updated Title", // optional
"description": "...", // optional
"url_id": "new-url", // optional, must be unique
"media_gallery": [ // optional — replaces current gallery; old images are deleted
{ "type": "image", "mediaId": "abc123", "mediaUrl": "https://..." }
],
"visibility": "public", // optional: public | unlisted | archived
// a new value cancels a visibility change scheduled in the dashboard
// Only accepted when effective type is "event":
"eventStartAt": "2026-05-01T...", // optional
"eventEndAt": "2026-05-01T...", // optional
"eventAddress": "Jakarta", // optional
"eventTimezone": "Asia/Jakarta" // optional
// Sending eventStartAt/eventEndAt/eventTimezone on a digital_product service,
// or alongside type:"digital_product", → VALIDATION_ERROR
}Response
// 200 OK
{ "success": true, "data": { cuid, title, url_id, type, description, media_gallery,
eventStartAt, eventEndAt, eventScheduleType, eventAddress, eventGmapsLink,
eventTimezone, visibility, createdFrom, createdAt, updatedAt,
"url_link": "https://goakal.com/your-organization/my-event" } }Example
curl -X PATCH https://goakal.com/service/api/v1/services/clxxx \
-H "X-Api-Key: ak_..." \
-H "Content-Type: application/json" \
-d '{"description":"New description","media_gallery":[{"type":"image","mediaId":"abc","mediaUrl":"https://..."}]}'Error Codes
VALIDATION_ERROR— Event-only field sent when effective type is digital_product, or invalid media_gallery formatUNSUPPORTED_OPERATION— visibility sent for a draft service — publish it in the dashboard first (409)Landing Data
/services/:cuid/landing-dataRead the landing page data an integration can set: daftarPengajar and daftarDeskripsi. Read this before a PATCH that adds or changes one block.
Response
{
"success": true,
"data": {
"cuid": "clxxx",
"landingData": { "daftarPengajar": [ ... ], "daftarDeskripsi": [ ... ] },
"updatedAt": "..."
}
}Example
curl https://goakal.com/service/api/v1/services/clxxx/landing-data \ -H "X-Api-Key: ak_..."
/services/:cuid/landing-dataSet top-level landing page fields. Each field you send replaces that whole list (daftarDeskripsi is replaced, not appended); fields you do not send are kept. Unknown fields are rejected with VALIDATION_ERROR. deskripsi and courseDetail[].detail are rich text: send HTML (<p>, <strong>, <em>, <a>, <ol>/<ul> with <li>) or Markdown with one list item per line, which is converted to HTML on save. Other text fields are plain text.
Request Body
{
"optionalSectionVisibility": { "DESKRIPSI": true }, // DEPRECATED — accepted but ignored, has no effect
"daftarPengajar": [ // optional — instructor list
{
"foto": { "imageUrl": "https://...", "imageId": "abc" },
"nama": "Budi Santoso",
"title": "Senior Developer"
}
],
"daftarDeskripsi": [ // optional — description / testimonial blocks
{
"type": "deskripsi",
"title": "Apa yang akan kamu pelajari",
"deskripsi": "Kamu akan belajar:\n\n1. Dasar HTML\n2. CSS", // Markdown or HTML
"courseDetail": [{ "title": "Modul 1", "detail": "- Pengenalan\n- Instalasi" }]
},
{
"type": "testimonial",
"title": "Testimoni Peserta",
"daftarTestimonial": [{
"photo": { "imageUrl": "https://...", "imageId": "xyz" },
"name": "Siti", "role": "Student", "description": "Great course!",
"gallery": { "imageUrl": "https://...", "imageId": "gal1" }
}]
}
]
// any other field → VALIDATION_ERROR
}Response
// 200 OK
{ "success": true, "data": { "cuid": "clxxx", "landingData": { ...merged... }, "updatedAt": "..." } }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":"Developer"}]}'Error Codes
VALIDATION_ERROR— Unknown field provided — only the listed fields are allowedNOT_FOUND— Service not found or not owned by your organizationPrice Schemes
/services/:cuid/price-schemesList all price schemes for a class, including linked benefits.
Response
// 200 OK
{
"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": "...", "benefits": [...],
"url_link": "https://goakal.com/your-organization/my-event/abc123/apply"
}]
}Example
curl https://goakal.com/service/api/v1/services/clxxx/price-schemes \ -H "X-Api-Key: ak_..."
/services/:cuid/price-schemesCreate a price scheme. Only supported for event or digital_product services. At least one MESSAGE benefit is required.
Request Body
{
"title": "Early Bird", // required
"mainAmount": 500000, // required, price amount, must be >= 0
"currency": "IDR", // optional: IDR | USD
"type": "fixedAmount", // required: fixedAmount | openAmount
// openAmount → stored as payAsYouWish
"minimumOpenAmount": 50000, // required when type=openAmount; omit for fixedAmount; >= 0
"order": 0, // optional, display order, default: 0
"checklistDescription": ["Item 1"], // optional
"isFirstPaymentEndDateEnabled": false, // optional
"firstPaymentEndDate": "2026-05-01T23:59:59+07:00", // optional, ISO-8601 with timezone
"openingDate": "2026-04-20T09:00:00+07:00", // optional, ISO-8601 with timezone. Before it the landing
// page shows "Belum dibuka" with a countdown and checkout refuses
// this price scheme. Must be before firstPaymentEndDate
"isPriceShownBeforeOpening": true, // optional, default: true. false hides the price until openingDate
"isShow": true, // optional, default: true
"isQuotaEnabled": false, // optional
"quotaMax": 100, // optional, max enrollments, must be >= 0
"benefits": [ // REQUIRED — must include at least one MESSAGE benefit
// New benefit (created inline):
{ "type": "MESSAGE", "details": { "title": "Welcome", "sender_name": "Team", "message": "Hello!" } },
// OR existing benefit by ID:
{ "id": 5 }
]
}Response
// 201 Created
{
"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"
}
}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":"Hello!"}}]}'Error Codes
UNSUPPORTED_OPERATION— Service type does not support price schemesVALIDATION_ERROR— benefits missing, no MESSAGE benefit, invalid benefit format, removed field sent, or openingDate invalid or not before firstPaymentEndDate/services/:cuid/price-schemes/:idUpdate a price scheme. The price scheme must belong to the service in the URL. Use isShow to show or hide it from students. quotaUsed is read-only and cannot be updated.
Request Body
{
"isShow": false, // hide price scheme
"title": "...", // optional
"mainAmount": 450000, // optional, >= 0; cannot be lowered below the
// discountAmount of a promo already applied to this
// scheme -> PROMO_DISCOUNT_CONFLICT (409) naming them
"order": 1, // optional
"checklistDescription": [...], // optional
"isFirstPaymentEndDateEnabled": true, // optional
"firstPaymentEndDate": "2026-05-01T23:59:59+07:00", // optional
"openingDate": "2026-04-20T09:00:00+07:00", // optional; null or "" removes it
"isPriceShownBeforeOpening": false, // optional
"isQuotaEnabled": true, // optional
"quotaMax": 50 // optional, max enrollments
// quotaUsed → VALIDATION_ERROR (read-only, system-managed)
}Response
// 200 OK
{ "success": true, "data": { cuid, title, mainAmount, currency,
type (payAsYouWish|fixedAmount), order, checklistDescription,
minimumOpenAmount, isFirstPaymentEndDateEnabled, firstPaymentEndDate,
openingDate, isPriceShownBeforeOpening,
isShow, isQuotaEnabled, quotaMax, createdFrom, createdAt, updatedAt,
"url_link": "https://goakal.com/your-organization/my-event/abc123/apply" } }Example
# Hide a 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}'Error Codes
NOT_FOUND— Price scheme not found, or does not belong to the service in the URLVALIDATION_ERROR— quotaUsed sent (read-only), installment field sent, or openingDate invalid or not before firstPaymentEndDate (the stored deadline counts when the request does not send one)Benefits
/benefitsList all benefits for your organization. Optionally filter by service using ?serviceCuid= to return only benefits linked to that service's price schemes.
Request Body
// Query params: serviceCuid=clxxx // optional — filter to benefits linked to this service
Response
// 200 OK
{ "success": true, "data": [{ "id": 1, "type": "WA_INVITATION", "details": { ... },
"createdFrom": "external-api", "createdAt": "...", "updatedAt": "..." }] }Example
# All 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_..."
/benefitsCreate a new benefit. Only MESSAGE and WA_INVITATION types are supported via this API.
Request Body
// WA_INVITATION
{ "type": "WA_INVITATION", "details": { "title": "Group A", "invitation_url": "https://chat.whatsapp.com/ABC" } }
// MESSAGE
{ "type": "MESSAGE", "details": { "title": "Welcome", "sender_name": "Team", "message": "Hello!" } }
// Other types (FILE, CERTIFICATE, WEBINAR, etc.) → VALIDATION_ERRORResponse
// 201 Created
{ "success": true, "data": { "id": 1, "type": "WA_INVITATION", "details": { ... },
"createdFrom": "external-api", "createdAt": "...", "updatedAt": "..." } }Example
curl -X POST https://goakal.com/service/api/v1/benefits \
-H "X-Api-Key: ak_..." \
-H "Content-Type: application/json" \
-d '{"type":"WA_INVITATION","details":{"title":"Group A","invitation_url":"https://chat.whatsapp.com/ABC"}}'Error Codes
DUPLICATE_BENEFIT— WA_INVITATION with this URL already exists for your organizationVALIDATION_ERROR— Unsupported type — only MESSAGE and WA_INVITATION are accepted/benefits/:idUpdate an existing benefit.
Request Body
{
"type": "WA_INVITATION", // required
"details": { ... } // required
}Response
// 200 OK
{
"success": true,
"data": {
"id": 1, "type": "WA_INVITATION", "details": { ... },
"createdFrom": "external-api", "createdAt": "...", "updatedAt": "...",
"impactedPriceSchemes": [{ "cuid": "clyyy", "title": "Early Bird" }]
}
}Example
curl -X PATCH https://goakal.com/service/api/v1/benefits/1 \
-H "X-Api-Key: ak_..." \
-H "Content-Type: application/json" \
-d '{"type":"WA_INVITATION","details":{"title":"New Group","invitation_url":"https://chat.whatsapp.com/XYZ"}}'impactedPriceSchemes — a list of price schemes currently linked to this benefit. Updating the benefit will affect all of them immediately. Review this list before confirming your update.Promos
/services/:cuid/promosList all promo codes for a class.
Response
// 200 OK
{
"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": null,
"discounts": [{ "priceSchemeCuid": "clyyy", "discountAmount": 50000 }],
"promoLink": "https://goakal.com/organization-url/class-url?promo=launch50",
"createdFrom": "external-api",
"createdAt": "...", "updatedAt": "..."
}]
}Example
curl https://goakal.com/service/api/v1/services/clxxx/promos \ -H "X-Api-Key: ak_..."
/services/:cuid/promosCreate a promo code for a class.
Request Body
{
"title": "Launch Promo", // required
"promo_code": "LAUNCH50", // required, stored lowercase, unique per class
"isLimited": true, // optional, default: false
"quota": 100, // optional, max uses (if isLimited)
"time_start": "2025-01-01T...", // optional, ISO 8601
"time_end": "2025-12-31T...", // optional, ISO 8601
"notes": "Launch discount", // optional
"discounts": [{ // optional
"priceSchemeCuid": "clyyy", // must belong to this service — VALIDATION_ERROR otherwise
"discountAmount": 50000 // >= 0 and <= that scheme's mainAmount, so the
// total payable can never go negative.
// openAmount schemes are exempt from the upper bound.
}]
}Response
// 201 Created
{ "success": true, "data": { "id": 1, "title": "Launch Promo", "promo_code": "launch50",
"promoLink": "https://goakal.com/organization-url/class-url?promo=launch50",
"createdFrom": "external-api", ... } }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","discounts":[{"priceSchemeCuid":"clyyy","discountAmount":50000}]}'Error Codes
DUPLICATE_PROMO_CODE— Promo code already exists for this classVALIDATION_ERROR— priceSchemeCuid in discounts does not belong to this service/services/:cuid/promos/:idGet a single promo by ID.
Response
// 200 OK
{ "success": true, "data": { "id": 1, "title": "Launch Promo", "promo_code": "launch50",
"promoLink": "https://goakal.com/organization-url/class-url?promo=launch50",
"createdFrom": "external-api", ... } }Example
curl https://goakal.com/service/api/v1/services/clxxx/promos/1 \ -H "X-Api-Key: ak_..."
/services/:cuid/promos/:idUpdate a promo. All fields optional.
Request Body
{
"title": "Updated Promo", // optional
"promo_code": "NEW_CODE", // optional, unique per class
"quota": 200, // optional
"discounts": [{ // optional
"priceSchemeCuid": "clyyy", // must belong to this service — VALIDATION_ERROR otherwise
"discountAmount": 50000 // >= 0 and <= that scheme's mainAmount, so the
// total payable can never go negative.
// openAmount schemes are exempt from the upper bound.
}]
}Response
// 200 OK
{ "success": true, "data": { id, title, promo_code, isLimited, quota,
time_start, time_end, notes, discounts,
"promoLink": "https://goakal.com/organization-url/class-url?promo=...",
createdFrom, createdAt, updatedAt } }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}'Error Codes
NOT_FOUND— Promo not foundDUPLICATE_PROMO_CODE— Code already taken by another promoVALIDATION_ERROR— priceSchemeCuid in discounts does not belong to this serviceTransactions
/services/:cuid/transactionsList transactions for a service with optional filtering and pagination.
Request Body
// Query params: status=PAID // optional: PAID | SETTLED | PENDING | EXPIRED | FAILED priceSchemeTitle=Early // optional, partial match page=1 // optional, default: 1 pageSize=20 // optional, default: 20, max: 100 _schema=true // optional, returns field descriptions
Response
// 200 OK
{
"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,
// invoiceUrl only present when status is PENDING:
"invoiceUrl": null
}],
"meta": { "page": 1, "pageSize": 20, "total": 45 }
}Example
curl "https://goakal.com/service/api/v1/services/clxxx/transactions?status=PAID&page=1" \ -H "X-Api-Key: ak_..."
Error Codes
NOT_FOUND— Service not found or not owned by your organizationReviews
/services/:cuid/reviewsList published testimonials for a service. Only reviews with submitted testimonial text are returned, ordered by most recent first.
Request Body
// Query params: page=1 // optional, default: 1 pageSize=20 // optional, default: 20, max: 100
Response
// 200 OK
{
"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 }
}Example
curl "https://goakal.com/service/api/v1/services/clxxx/reviews?page=1&pageSize=20" \ -H "X-Api-Key: ak_..."
Error Codes
NOT_FOUND— Service not found or not owned by your organizationRegistration Prefill
There is currently no API to create transactions directly. Instead, you can redirect your users to the registration page and pass their data as query parameters to prefill the form. This helps them register faster without re-typing their details — and the form remains fully editable so they can correct any value.
URL Format
https://goakal.com/{your-organization}/{serviceUrlId}/{priceSchemeShortId}/applySupported Query Params
name — prefills the buyer's nameemail — prefills the buyer's email addressphone — prefills the buyer's phone number (e.g. 6281234567890)Example
https://goakal.com/my-school/my-class/abc123/apply?name=John+Doe&email=john%40example.com&phone=6281234567890
The priceSchemeShortId can be found in the url_link field returned by the price scheme endpoints.
Image Uploads
/services/:cuid/imagesUpload an image for the landing page media gallery. Returns imageUrl to include in media_gallery when creating or updating the service.
Request Body
// multipart/form-data file: <image file> // required, image/* types, max 10MB (JPEG, PNG, GIF, WebP) — SVG is refused
Response
// 201 Created
{
"success": true,
"data": {
"imageId": "abc123",
"imageUrl": "https://...",
"fileName": "thumbnail.jpg",
"contentType": "image/jpeg",
"size": 204800
}
}Example
curl -X POST https://goakal.com/service/api/v1/services/clxxx/images \
-H "X-Api-Key: ak_..." \
-F "file=@thumbnail.jpg"
# Then use the returned imageId and imageUrl in PATCH /services/:cuid:
# { "media_gallery": [{ "type": "image", "mediaId": "<imageId>", "mediaUrl": "<imageUrl>" }] }