SapaganDocs sapagan.com

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

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 callSapagan
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}/eventsRecords an event for the person.
POST /eventsAn anonymous event. Requires anonymous_id.
PUT /customers/{id}/devicesRegisters 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_id never creates.
  • Event timestamp is unix seconds. An ISO string is tolerated. The event id is the dedupe key. A name is at most 255 characters.
  • With the workspace setting identifier_mode set to id_or_email, a path value that contains @ is an email and the person is found by it. The default is id.
  • A write for a deleted person is 200 and is dropped.
  • Success is 200 with {"meta":{"request_id":...}}. Errors are {"meta":{"errors":[...]}} or {"meta":{"error":"..."}}.

Track API v2#

Base: /api/v2.

CallNotes
POST /entityOne 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 id to 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.ioIn Sapagan
SegmentsSegments: conditions on attributes and events, built in the console.
Push and email templatesTemplates 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.
CampaignsBroadcasts (/v1/broadcasts).
Campaigns triggered by eventsJourneys.
Transactional APIPOST /v1/send.
Subscription topicsConsent topics.
Webhooks (reporting)The webhook step in a journey.

A safe order#

  1. Create a Track key in a development workspace and point a copy of your backend at it. Watch events and people arrive.
  2. Move the SDK in a build behind a remote flag, so you can run both.
  3. Move templates and one journey. Send to test people.
  4. Switch production over when the numbers match.