Migrate
Migrating from Customer.io
Point a Customer.io Track API backend at Sapagan, swap the app SDK, and map your segments and templates.
Sapagan accepts the Customer.io Track API v1 and v2 on /api/v1 and /api/v2. A backend that calls Customer.io today can switch by changing its base URL and credentials. Then you can move, one piece at a time, to the native API.
Credentials#
Create a Track key (ktg_track_<prefix>_<secret>) in the console. Customer.io's Track API uses HTTP Basic with your site id and API key. Sapagan uses the same scheme: the key's prefix is the user name and its secret is the password.
curl -X PUT "$SAPAGAN_URL/api/v1/customers/user-42" \
-u "$SAPAGAN_KEY_PREFIX:$SAPAGAN_KEY_SECRET" \
-H "Content-Type: application/json" \
-d '{ "email": "budi@example.com", "name": "Budi Santoso" }'const auth = Buffer.from(`${process.env.SAPAGAN_KEY_PREFIX}:${process.env.SAPAGAN_KEY_SECRET}`).toString("base64");
await fetch(`${process.env.SAPAGAN_URL}/api/v1/customers/user-42`, {
method: "PUT",
headers: { Authorization: `Basic ${auth}`, "Content-Type": "application/json" },
body: JSON.stringify({ email: "budi@example.com", name: "Budi Santoso" }),
});Only Track keys work on these routes. A bad key is 401, even for a path that does not exist. Errors use Customer.io's status codes and body shapes, so a client that handles them today keeps working.
Track API v1#
Base: /api/v1.
| Customer.io call | Sapagan |
|---|---|
PUT /customers/{id} | Creates or updates the person. email and phone fill the contact fields and stay attributes. id in the body is dropped, the path wins. _update: true never creates. |
DELETE /customers/{id} | Deletes the person (soft delete now, erasure within 30 days). Deleting an unknown person is 200. |
POST /customers/{id}/events | Records an event for the person. |
POST /events | An anonymous event. Requires anonymous_id. |
PUT /customers/{id}/devices | Registers a device. platform is ios, android or web, case-insensitive. last_used and attributes are accepted and not stored. |
DELETE /customers/{id}/devices/{token} | Removes the person's own token. An unknown one is 200. |
Details that differ from what you may expect:
- A person Sapagan has not seen is created on first sight by
PUT, events and devices.cio_idnever creates. - Event
timestampis unix seconds. An ISO string is tolerated. The eventidis the dedupe key. A name is at most 255 characters. - With the workspace setting
identifier_modeset toid_or_email, a path value that contains@is an email and the person is found by it. The default isid. - A write for a deleted person is
200and is dropped. - Success is
200with{"meta":{"request_id":...}}. Errors are{"meta":{"errors":[...]}}or{"meta":{"error":"..."}}.
Track API v2#
Base: /api/v2.
| Call | Notes |
|---|---|
POST /entity | One entity. |
POST /batch | { "batch": [...] }, at most 1000 items. Every item is validated first, then all are written in one transaction. One bad item rejects the batch with 400 naming it. |
Supported: type: person and type: object, with the actions identify, add_relationships and delete_relationships. Success is 200 {}.
Objects and relationships map to stores in a marketplace workspace: an identify on an object upserts the store, and add_relationships with role: follower or buyer links a person to it. Other roles still upsert the store and are recorded as unmapped. In an own brand workspace, which has no stores, object and relationship commands are recorded as unmapped and the call still answers 200, so your backend does not break. Delivery entities and the event action are not supported.
What is not built#
- CDP endpoints (
/cdp/v1). The routes for Segment-style SDK traffic are not live. Only the key kind and the authentication exist. Do not point a CDP-key SDK at Sapagan yet. Use the Flutter SDK below. - Rate limiting and idempotency keys on the compatibility routes. Customer.io has none of the second. Use the event
idto dedupe. - Anything unmapped (an unknown object type, a role without a mapping) is recorded for you to inspect, and is not an error.
Swap the app SDK#
For Flutter, sapagan_flutter has the same shape as customer_io. See the table in Flutter. Use an app key and an identity token provider. For the web, see Web.
Push opens: a push without data['k_did'] is not Sapagan's and is never reported, so you can run both vendors side by side during the move.
Map your content#
| In Customer.io | In Sapagan |
|---|---|
| Segments | Segments: conditions on attributes and events, built in the console. |
| Push and email templates | Templates with Liquid. Sapagan renders in a sandbox, with the roots customer and event and an allow list of filters. Check each template with POST /v1/templates/preview. |
| Campaigns | Broadcasts (/v1/broadcasts). |
| Campaigns triggered by events | Journeys. |
| Transactional API | POST /v1/send. |
| Subscription topics | Consent topics. |
| Webhooks (reporting) | The webhook step in a journey. |
A safe order#
- Create a Track key in a development workspace and point a copy of your backend at it. Watch events and people arrive.
- Move the SDK in a build behind a remote flag, so you can run both.
- Move templates and one journey. Send to test people.
- Switch production over when the numbers match.