Connect your own product

Who should connect

The contract answers one question: how does a product that issues its own promo codes hand those codes to CodeDock.

“Issues its own” is the only requirement — where the product runs does not matter: a SaaS website, an Android app with a redeem entry, desktop software sold as license codes, a game handing out gift codes, an iOS app selling subscriptions on the web. As long as your own backend issues and redeems the codes, it applies. App Store promo codes and offer codes do not go through this contract; they are imported as files.

Products you can connect

The contract is deliberately tiny — closer to RSS than to OAuth: no callbacks, no authorization page, no middle server. The implementer is usually a CodeDock user themselves.

The connection

In CodeDock, the user fills in two things: a base URL and a token. Every request then looks like this:

GET {base}/v1/manifest HTTP/1.1
Authorization: Bearer cdk_ro_9f2c…
Accept: application/json

• {base} must be https. http://localhost, 127.0.0.1, and *.local are excepted for local development — a token crossing the public internet in cleartext is as good as pasted into a chat.
• The token must be read-only and scoped to the three endpoints in this contract.
• CodeDock stores it in the device Keychain and keeps it out of backup files — after restoring onto a new phone it has to be entered again, on purpose.

The three endpoints

All three endpoints accept GET only and return application/json (UTF-8). All timestamps are ISO 8601 with a timezone (UTC recommended).

The client ignores fields it does not recognize, so within v1 things only get added: new fields never require a version bump.

{
  "spec": "codedock.source/1",
  "product": {
    "id": "prod_inkwell",
    "name": "Inkwell",
    "website_url": "https://inkwell.app",
    "icon_url": "https://inkwell.app/icon.png",
    "redeem_url_template": "https://inkwell.app/redeem?code={code}"
  },
  "capabilities": ["redemption_counts"]
}

{
  "data": [
    {
      "id": "offer_press",
      "name": "Press preview",
      "summary": "3 months of Pro, free",
      "usage": "single_use",
      "status": "active",
      "expires_at": "2026-12-31T23:59:59Z"
    }
  ],
  "next_cursor": null
}

{
  "data": [
    {
      "id": "code_8x2k",
      "offer_id": "offer_press",
      "code": "INK-7KQ2-M9XD",
      "status": "active",
      "max_redemptions": 1,
      "times_redeemed": 0,
      "last_redeemed_at": null
    }
  ],
  "next_cursor": "b2Zmc2V0OjEwMA"
}

Pagination

/v1/offers and /v1/codes both paginate by cursor:

GET {base}/v1/codes?limit=100
GET {base}/v1/codes?limit=100&cursor=b2Zmc2V0OjEwMA

• limit defaults to 100 and caps at 500.
• A null next_cursor in the response means the end. Cursors are opaque to the client.
• Within a single sync, the server should keep pages stable — no duplicates, no gaps (sorting by id or creation time is enough).

Sync semantics — how CodeDock reads your data

Every sync pulls all pages of both collections and reconciles the local side against that snapshot. v1 has no incremental sync (no updated_since) and therefore needs no tombstones: absent from the snapshot means deleted.

CodeDock never writes back: hand out a code in the app and your server never knows. Single-use codes are best handed out through CodeDock alone; if the same code goes out twice from two places, CodeDock cannot deduplicate that for you.

If any page returns non-2xx, times out, or fails to parse, the whole sync is abandoned and local data stays untouched. The UI says “last sync failed · data is 3 hours old” instead of pretending the data is fresh.

Frequency: CodeDock syncs when the app returns to the foreground and the last attempt is more than 10 minutes old; pull-to-refresh syncs immediately. It does not poll in the background.

Who decides what

How states change

• A single-use code with times_redeemed ≥ 1 that CodeDock handed out: marked “redeemed” and leaves the follow-up list.
• A single-use code with times_redeemed ≥ 1 that CodeDock never handed out: recorded as “redeemed elsewhere” — out of stock, counted as redeemed, attributed to no one.
• times_redeemed falling back to 0 (e.g. a refund reverting a redemption): the “redeemed” mark is undone and the code returns to sent-but-unredeemed.
• A code disabled, an offer archived, or a code missing from the snapshot: un-sent ones leave the stock; sent ones stay on the record, marked disabled or removed.
• Deleting a person never deletes the record; the server deleting a code does not either. “Who you sent it to in March” has already happened.

Errors

Express the category with an HTTP status code and give one readable reason in the body, e.g. {"error":{"code":"invalid_token","message":"Token revoked"}}.

Compared with established platforms

These fields were not invented from scratch — they are the greatest common divisor of the promo-code models of the mainstream payment platforms. If your codes already live in one of them, implementing this contract is mostly a field rename. If one Stripe Coupon mixes single-use and multi-use codes, split it into two offers — usage is the watershed for how CodeDock keeps the books.

Versioning

The spec field and the /v1 in the path evolve together. Breaking changes go to /v2; v1 endpoints should keep working. Within v1, fields only get added: the client ignores unknown fields and unknown capabilities; an unknown usage makes it skip that offer, and an unknown status is treated as disabled — better to under-report than to report wrong.

Free and Pro

The free tier includes one product profile and ten contacts, and covers importing App Store codes, sending, reminders, and history. Connecting your own backend is part of Pro. For the full differences between free and Pro, see the FAQ.