Trigger postcards from your own system with the TouchDrop API

Two calls from your system, and one read when you need it.

1. Send us a person. One request per person, when an event happens in your system or on a schedule you choose. TouchDrop posts nothing without it.
2. Tell us when that person comes back. A purchase, a reactivated subscription, whatever counts as a return for you. Without it, your reporting shows what a campaign cost and no revenue against it.
3. Ask what happened to a person. Optional. The answer confirms whether a card was produced and returns the discount code printed on it, which your checkout needs if you have no connected store.

• Create a campaign in TouchDrop and choose Webhook Trigger. Its Trigger URL appears on the campaign page. TouchDrop reviews each new campaign once before its first cards print.
• If you will report orders, generate an API token in Settings, on the Integrations tab, under API access.
• Set your website in Settings, on the Brand tab, so the QR code on each card has a page of yours to land on.

There are two tokens. Treat both like passwords: they can queue printed, paid-for mail.

Send the token in a header:

POST /api/webhooks/campaign-trigger HTTP/1.1
Host: touchdrop.com.au
Authorization: Bearer wht_your_token
Content-Type: application/json

On the trigger and status endpoints, X-TouchDrop-Token: wht_your_token works as well, for platforms that reserve the Authorization header.

If your platform cannot set headers, put the token in the path instead: POST /api/webhooks/campaign-trigger/wht_your_token. Prefer the header. A token in a URL ends up in access logs, proxies and browser history along the way.

POST https://touchdrop.com.au/api/webhooks/campaign-trigger

Enrols one person into one campaign. The campaign already holds the artwork, the offer and the sending rules; this call says who receives it.

If your platform cannot send a nested object, send the address fields at the top level instead (address1, address2, city, state, postcode or zip, country).

Address fields by account region:

Example request:

curl -X POST https://touchdrop.com.au/api/webhooks/campaign-trigger \
  -H 'Authorization: Bearer wht_your_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "jane@example.com.au",
    "first_name": "Jane",
    "external_id": "customer_123",
    "address": {
      "address1": "12 Example Street",
      "city": "Fitzroy",
      "state": "VIC",
      "postcode": "3065",
      "country": "AU"
    }
  }'

Example response (202 Accepted):

{
  "status": "queued",
  "entryId": "3f2b8c1e-0d4a-4b8e-9c61-2a7f5e9d1b40",
  "campaignStatus": "active",
  "monthlyAllowance": { "cap": 500, "used": 12, "remaining": 488 },
  "requestId": "req_a1b2c3d4e5f60718"
}

Store the entryId against your customer record. You need it to check the outcome later.

What a 202 tells you. TouchDrop accepted the person. If your account has no other source for the address, it also means the address passed the check, because an unusable one gets a 422 instead. A 202 does not confirm a printed card: suppression, frequency caps and the monthly allowance apply during processing a few minutes later. The status endpoint confirms the outcome.

While a campaign is in draft, awaiting review or paused, triggers still return 202 and the response carries a notice. A campaign that has never gone live holds its queue until it does. Once a campaign has gone live, a queued person who waits more than 7 days for it to resume (for example after the postage balance ran out) expires without a card, and TouchDrop alerts you.

Treat any response outside 200 and 202 as a failed action. Many platforms report only the status code, so route failures to a queue someone reviews.

GET https://touchdrop.com.au/api/webhooks/campaign-trigger/status?entry_id=3f2b8c1e-0d4a-4b8e-9c61-2a7f5e9d1b40

Use the campaign trigger token, in the header as above. You can look up by email instead of entry_id, but prefer the ID: an email in a query string travels into proxy and CDN logs.

{
  "entryId": "3f2b8c1e-0d4a-4b8e-9c61-2a7f5e9d1b40",
  "email": "jane@example.com.au",
  "entryStatus": "processed",
  "skipReason": null,
  "receivedAt": "2026-10-01T10:00:02Z",
  "processedAt": "2026-10-01T10:04:11Z",
  "campaignStatus": "active",
  "mailing": {
    "status": "shipped",
    "scheduledAt": "2026-10-01T10:04:11Z",
    "shippedAt": "2026-10-02T09:00:00Z",
    "isHoldout": false
  },
  "discount": {
    "code": "WB-4KD2",
    "status": "active",
    "expiresAt": "2026-12-01T00:00:00Z"
  }
}

shipped means the card was printed and handed to the postal service on that date. Letter post is not tracked to the door, so no one can confirm the day it arrived. If you have no connected store, read discount.code and load it into your checkout, or your checkout will reject the code printed on the card.

Other skip reasons can appear. Treat one you don't recognise as information and keep processing.

POST https://touchdrop.com.au/api/webhooks/conversion

Use your API token (tda_). You need this call when your orders do not come from a store connected to TouchDrop.

curl -X POST https://touchdrop.com.au/api/webhooks/conversion \
  -H 'Authorization: Bearer tda_your_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_id": "SUB-1001",
    "email": "jane@example.com.au",
    "value": 120.50,
    "currency": "AUD",
    "type": "subscription_initial"
  }'

{ "status": "attributed", "orderId": "SUB-1001", "revenueTracked": 120.5, "requestId": "req_9f8e7d6c5b4a3921" }

How an order counts towards a campaign. It counts when someone uses the discount code printed on the card, at any time. It also counts when the email or delivery address matches someone the campaign mailed, inside the campaign's attribution window: 60 days from the card's estimated arrival, unless agreed otherwise. Each order counts towards one campaign at most. Send every order; TouchDrop decides which ones attribute.

If your account also has a connected store, the response carries a warnings entry: TouchDrop already imports that store's orders, so reporting the same sale here under another ID counts it twice.

For subscriptions, use subscription_initial for the reactivation the card won and subscription_renewal for the rebills after it. That keeps revenue the card created apart from revenue you were already collecting.

POST https://touchdrop.com.au/api/webhooks/conversion/refund

Use your API token and send { "order_id": "SUB-1001" }. If you sent source_system with the conversion, send the same value here.

A refund removes the whole conversion from revenue and keeps the record. Repeat calls change nothing. An order that never attributed returns 404, because TouchDrop does not store unmatched conversions. This version does not support partial refunds.

Error responses are JSON with an error message. Where it applies you also get a stable code and a details list. Branch on code, never on the wording of error; TouchDrop may reword messages and will not change codes. Responses carry an X-Request-Id header. Quote it when you contact support.

Retries are safe. There is no batch endpoint: send one person per request, in a loop.

TouchDrop limits how many requests a caller can send per minute. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, so a large import can pace itself. On a 429, honour Retry-After. If you plan a one-off bulk release, tell TouchDrop in advance.

Most marketing and CRM platforms can call a webhook when someone enters a segment or a flow step fires. In Klaviyo, add a webhook step to a flow:

• Method: POST
• URL: https://touchdrop.com.au/api/webhooks/campaign-trigger
• Headers: Authorization: Bearer wht_your_token and Content-Type: application/json

{
  "email": "{{ person.email }}",
  "first_name": "{{ person.first_name|default:'' }}",
  "last_name": "{{ person.last_name|default:'' }}",
  "source": "klaviyo-winback-flow",
  "address": {
    "address1": "{{ person|lookup:'$address1'|default:'' }}",
    "address2": "{{ person|lookup:'$address2'|default:'' }}",
    "city": "{{ person|lookup:'$city'|default:'' }}",
    "state": "{{ person|lookup:'$region'|default:'' }}",
    "postcode": "{{ person|lookup:'$zip'|default:'' }}",
    "country": "AU"
  }
}

If TouchDrop is connected to your Shopify store, you can leave the address out and send email and name: TouchDrop then uses an address from the customer's recent Shopify orders. Otherwise check that every field holds a value for the people in that flow. Most platforms send a missing field as an empty string, which reaches TouchDrop as a blank address and returns a 422.

1. Create the Webhook Trigger campaign and copy its Trigger URL.
2. Send one trigger with a real address you control. Expect 202 and store the entryId.
3. Send one with a broken address (no postcode) and a different email. Expect 422 with code: "invalid_address". This proves your system sees failures.
4. Poll the status endpoint until entryStatus is processed, then read mailing.status and discount.code.
5. Post a test conversion for that person. Expect recorded_unattributed until the card's estimated arrival date, then attributed. Refund the test order afterwards so it does not count as revenue.
6. Release a small group first, check the count your system sends against what TouchDrop accepted, then switch on the full flow. Ask TouchDrop for a hard campaign ceiling if you want one.

TouchDrop stores each request against its campaign for processing and audit, and drops any field this page does not list. Do not send payment details or special-category data; no endpoint accepts them. TouchDrop never sells your customer data and shares it only with its print partner to produce your cards. For a data processing agreement or a deletion request, email support@touchdrop.com.au.