Tags (pay link handles)

A Tag is a personal pay link handle. It gives an Account a readable alias for its invoice payment URL, so you can share a short link instead of a long one. Wingspan returns the resulting link in paymentUrl.

Prerequisites

• A credential with users.customization:read to read Tags and users.customization:write to create, change or delete them.
• X-Wingspan-Account set to the Account that owns the Tag, when you act for another Account. See Acting on behalf of accounts.

Endpoints

Create a Tag

Only name is required.

curl -X POST https://api.wingspan.app/v3/platform/tags \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "X-Wingspan-Account: Nw7kQ2pLx9RtVb3mHc5dZa" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Design retainer", "slug": "design-retainer", "amount": 1500, "currency": "USD" }'

The response is 201 with the Tag: id, accountId, name, slug, description, amount, currency, isActive, paymentUrl, events, actors and metadata. The example values above are illustrative.

Change or delete a Tag

Update a Tag uses JSON Merge Patch. You can change name, slug, description, amount, isActive and metadata. currency is set at creation and is not in the update body. Set isActive to false to stop using a Tag without deleting it.

Delete a Tag removes the Tag and its handle for good and returns 204.

List Tags

List Tags returns the Tags of the Account. It takes page[size] and page[token] only. See Pagination.

Errors

Webhook events

Tag lifecycle events are published as webhooks. See Webhooks and events to subscribe.