Tags

Tags are a part of the segmentation engine. Tags can be used to manually, or in this case, programmatically group members to a specific partition.

The tag model

The tag model contains the info about a specific tag.

Properties

  • Name
    tag
    Type
    string
    Description

    The human readable variant of the tag label.

  • Name
    external_reference
    Type
    string
    Description

    A identifier provided by the implementing party.

  • Name
    uuid
    Type
    string
    Description

    The WalletApp identifier for a tag.

  • Name
    created_at
    Type
    timestamp
    Description

    The timestamp of creation.

  • Name
    updated_at
    Type
    timestamp
    Description

    The timestamp of the last update.

  • Name
    brand_id
    Type
    string
    Description

    The id of the brand the tag is attached to.

Note

Because a user can have access to multiple organizations we require a organization_id to be passed by most requests. We will also return an organization reference in each response.

GET/tags

List all tags

This endpoint returns a list of all the tags the currently authenticated user has access to.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.get
    Type
    string
    Description

    The scope required to access this endpoint.

Request

GET
/tags
curl -X GET https://api.walletapp.co/tags 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

{
    "success": true,
    "data": [
        {
            "tag": "<tag>",
            "external_reference": "<external_reference>",
            "uuid": "<uuid>",
            "created_at": "<timestamp>",
            "updated_at": "<timestamp>",
            "brand_id": "<brand_id>"
        },
        ...
    ]
}
POST/tags

Create a tag

This endpoint allows you to create a tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    brand_id
    Type
    string|Required
    Description

    The id of the brand the tag is attached to.

  • Name
    external_reference
    Type
    string|Required
    Description

    The reference provided by the implementing party.

  • Name
    tag
    Type
    string|Required
    Description

    The human readable variant of the tag label.

Request

POST
/tags
curl -X POST https://api.walletapp.co/tags 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<brand_id>",
        "external_reference": "<external_reference>",
        "tag": "<tag>"
    }'

Response

{
    "success": true,
    "data": {
        "tag": "<tag>",
        "external_reference": "<external_reference>",
        "uuid": "<uuid>",
        "created_at": "<timestamp>",
        "updated_at": "<timestamp>",
        "brand_id": "<brand_id>"
    }
}
PUT/tags

Update a tag

This endpoint allows you to update a tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    tag_id
    Type
    string|Required
    Description

    The id of the tag to update.

  • Name
    brand_id
    Type
    string
    Description

    The id of the brand the tag is attached to.

  • Name
    external_reference
    Type
    string
    Description

    The reference provided by the implementing party.

  • Name
    tag
    Type
    string
    Description

    The identifier of the organization the product should be created for.

Request

PUT
/tags
curl -X PUT https://api.walletapp.co/tags 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<brand_id>",
        "external_reference": "<external_reference>",
        "tag": "<tag>"
    }'

Response

{
    "success": true,
    "data": {
        "tag": "<tag>",
        "external_reference": "<external_reference>",
        "uuid": "<uuid>",
        "created_at": "<timestamp>",
        "updated_at": "<timestamp>",
        "brand_id": "<brand_id>"
    }
}
DELETE/tags

Delete a tag

This endpoint allows you to delete a tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    tag_id
    Type
    string|Required
    Description

    The id of the tag to update.

  • Name
    brand_id
    Type
    string
    Description

    The id of the brand the tag is attached to.

Request

DELETE
/tags
curl -X DELETE https://api.walletapp.co/tags 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<brand_id>",
        "tag_id": "<tag_id>"
    }'

Response

{
    "success": true,
    "message": "Tag removed"
}
POST/tags/passes

Add a pass to a tag

This endpoint allows you to add a pass to a tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    tag_id
    Type
    string|Required
    Description

    The uuid or the external_reference of the tag.

  • Name
    pass_code
    Type
    string|Required
    Description

    The pass that needs to be added to the tag.

  • Name
    brand_id
    Type
    string
    Description

    The id of the brand the tag is attached to.

Request

POST
/tags/passes
curl -X POST https://api.walletapp.co/tags/passes 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<uuid>",
        "pass_code": "<code>",
        "tag_id": "<uuid>"
    }'

Response

{
    "success": true,
    "message": "Pass added to tag"
}
GET/tags/passes

Get passes

Get a list of all the passes for a specific tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.get
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    tag_id
    Type
    string|Required
    Description

    The uuid or the external_reference of the tag.

  • Name
    brand_id
    Type
    string|Required
    Description

    The id of the brand the tag is attached to.

Request

GET
/tags/passes
curl -X GET https://api.walletapp.co/tags/passes 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<uuid>",
        "tag_id": "<uuid>"
    }'

Response

{
    "success": true,
    "data": [
        {
            "pass_code": "<pass_code>"
        }
    ]
}
DELETE/tags/passes

Remove a pass from a tag

This endpoint allows you to remoe a pass from a tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    tag_id
    Type
    string|Required
    Description

    The uuid or the external_reference of the tag.

  • Name
    pass_code
    Type
    string|Required
    Description

    The pass that needs to be added to the tag.

  • Name
    brand_id
    Type
    string
    Description

    The id of the brand the tag is attached to.

Request

DELETE
/tags/passes
curl -X DELETE https://api.walletapp.co/tags/passes 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<uuid>",
        "pass_code": "<code>",
        "tag_id": "<uuid>"
    }'

Response

{
    "success": true,
    "message": "Pass removed from tag"
}
POST/tags/members

Add a member to a tag

This endpoint allows you to add a member to a tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    tag_id
    Type
    string|Required
    Description

    The uuid or the external_reference of the tag.

  • Name
    member_id
    Type
    string|Required
    Description

    The member_id that needs to be added to the tag.

  • Name
    brand_id
    Type
    string
    Description

    The id of the brand the tag is attached to.

Request

POST
/tags/members
curl -X POST https://api.walletapp.co/tags/members 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<uuid>",
        "member_id": "<uuid>",
        "tag_id": "<uuid>"
    }'

Response

{
    "success": true,
    "message": "Member added to tag"
}
POST/tags/members/bulk

Add members to a tag in bulk

Attach up to 2000 members to a tag in one call. Members that are already in the tag, that do not exist or that are not members of the brand are skipped silently; the call still succeeds.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Body parameters

  • Name
    brand_id
    Type
    string|Required
    Description

    The identifier of the brand.

  • Name
    tag_id
    Type
    string|Required
    Description

    The UUID or external reference of the tag.

  • Name
    users
    Type
    array|Required
    Description

    Member identifiers (UUIDs), 1 to 2000.

Returns 404 for an unknown brand or tag and 422 when users is empty or over 2000. Safe to repeat: already attached members are skipped.

Request

POST
/tags/members/bulk
curl -X POST https://api.walletapp.co/tags/members/bulk
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
    "brand_id": "<brand_id>",
    "tag_id": "<tag_id>",
    "users": [
        "<member_uuid_1>",
        "<member_uuid_2>"
    ]
}'

Response

{
    "success": true,
    "message": "Member added to tag"
}
GET/tags/members

Get members

Get a list of all the members for a specific tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.get
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    tag_id
    Type
    string|Required
    Description

    The uuid or the external_reference of the tag.

  • Name
    brand_id
    Type
    string|Required
    Description

    The id of the brand the tag is attached to.

Request

GET
/tags/members
curl -X GET https://api.walletapp.co/tags/members 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<uuid>",
        "tag_id": "<uuid>"
    }'

Response

{
    "success": true,
    "data": [
        {
            "identifier": "<member_id>",
            "email": "<email>"
        }
    ]
}
DELETE/tags/members

Remove a member from a tag

This endpoint allows you to remoe a member from a tag.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Request body

  • Name
    tag_id
    Type
    string|Required
    Description

    The uuid or the external_reference of the tag.

  • Name
    member_id
    Type
    string|Required
    Description

    The member_id that needs to be added to the tag.

  • Name
    brand_id
    Type
    string
    Description

    The id of the brand the tag is attached to.

Request

DELETE
/tags/members
curl -X DELETE https://api.walletapp.co/tags/members 
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<uuid>",
        "member_id": "<uuid>",
        "tag_id": "<uuid>"
    }'

Response

{
    "success": true,
    "message": "Member removed from tag"
}
POST/tags/{id}/vouchers

Issue a voucher to every member of a tag

Queues a coupon pass or a storecard pass for every member of a tag. The request returns immediately with status 202 and a job id; the passes are created in the background, in small rounds. Use the status endpoint below to follow the progress. No e-mail is sent.

The call is idempotent per member: a member who already received this coupon or storecard through this tag is skipped, so repeating the call never creates a second pass. Members whose earlier attempt failed are retried. While a job for the same tag and the same coupon or storecard is still queued or running, the same job is returned (already_running: true).

Members of the tag who are not (or no longer) a member of the brand are skipped.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.store
    Type
    string
    Description

    The scope required to access this endpoint.

Path parameters

  • Name
    id
    Type
    string|Required
    Description

    The uuid or the external_reference of the tag.

Request body

  • Name
    brand_id
    Type
    string|Required
    Description

    The id of the brand the tag is attached to.

  • Name
    coupon_id
    Type
    string|Required without storecard_id
    Description

    The identifier of the coupon to issue.

  • Name
    storecard_id
    Type
    string|Required without coupon_id
    Description

    The identifier of the storecard to issue. Send either coupon_id or storecard_id, not both.

  • Name
    expiration_date
    Type
    string|Optional
    Description

    Overrides the expiration of the coupon passes, for example 2030-12-31. Use no-date for passes that do not expire. Ignored for storecards.

Request

POST
/tags/{id}/vouchers
curl -X POST https://api.walletapp.co/tags/vip-members/vouchers
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "brand-1234",
        "coupon_id": "coupon-1234"
    }'

Response (202)

    {
        "success": true,
        "job_id": "0b6f4a52-7c1d-4e0a-9d52-3f1f6c2b8a10",
        "status": "queued",
        "total": 0,
        "processed": 0,
        "issued": 0,
        "skipped": 0,
        "failed": 0,
        "has_errors": false
    }
GET/tags/{id}/vouchers/{job}

Voucher job status

Returns the progress of a voucher job. Poll it until status is done. A job is only visible through the tag it was created for and to tokens with access to the organization.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    The token itself as a bearer token.

Abilities

  • Name
    tags.get
    Type
    string
    Description

    The scope required to access this endpoint. A token with tags.store can read the status as well.

Path and query parameters

  • Name
    id
    Type
    string|Required
    Description

    The uuid or the external_reference of the tag.

  • Name
    job
    Type
    string|Required
    Description

    The job_id returned by the POST request.

  • Name
    brand_id
    Type
    string|Required
    Description

    The id of the brand the tag is attached to, as a query parameter.

Response fields

  • Name
    status
    Type
    string
    Description

    queued, running, done or failed. failed means the coupon or storecard is no longer available; fix it and call the POST again.

  • Name
    total
    Type
    integer
    Description

    The number of members on the tag, counted when the job starts.

  • Name
    processed
    Type
    integer
    Description

    The number of members handled so far.

  • Name
    issued
    Type
    integer
    Description

    The number of passes created (or, for storecards, linked).

  • Name
    skipped
    Type
    integer
    Description

    Members who already received this voucher through this tag, or who are no longer a member of the brand.

  • Name
    failed
    Type
    integer
    Description

    Members for whom issuing failed. They are retried by the next POST for the same tag and coupon or storecard.

  • Name
    has_errors
    Type
    boolean
    Description

    True when at least one member failed.

Request

GET
/tags/{id}/vouchers/{job}
curl -X GET "https://api.walletapp.co/tags/vip-members/vouchers/0b6f4a52-7c1d-4e0a-9d52-3f1f6c2b8a10?brand_id=brand-1234"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

    {
        "success": true,
        "job_id": "0b6f4a52-7c1d-4e0a-9d52-3f1f6c2b8a10",
        "status": "done",
        "total": 250,
        "processed": 250,
        "issued": 248,
        "skipped": 2,
        "failed": 0,
        "has_errors": false,
        "started_at": "2030-01-15 10:00:02",
        "finished_at": "2030-01-15 10:01:40"
    }