Skip to main content
A QR Group is a flat collection of QR codes that can share a destination and a status. Update the group once and every child code that inherits picks up the change on the next scan.

​
When to use a group

  • A printed batch (a thousand table cards, a poster run) where every code should route the same place.
  • A campaign you want to flip live, pause, or retire as a unit.
  • A staging area for codes you’ll later split into different destinations — start them grouped, then break out the ones that need their own routing.

​
Inheritance model

When a QR code is in a group and the group has a destination_type (or status) set, the child’s own field can be left blank to inherit the group’s. If the child sets its own, the child wins. This lets you bulk-configure a whole campaign of codes from the group level, and break individual codes out later when they need to diverge. Inheritance is resolved at scan time, not cached on the child. Update the group and the very next scan on any inheriting child picks up the change. The same resolution applies to status: child first, then group, then default.

​
Worked example

Group with a shared destination and an inactive child: 
{
  "object": "qr_group",
  "id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "name": "Fall 2024 tabletop run",
  "status": "active",
  "destination": {
    "type": "page",
    "page": "a1c2e4f6-8b0d-4e2a-9c1b-3d5e7f9a2c4e",
    "chatbot": null,
    "knowledge_base": null,
    "url": null
  }
}
A child code that inherits: 
{
  "object": "qr_code",
  "id": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "public_slug": "abc1234",
  "group_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "status": "active",
  "destination": {
    "type": null,
    "page": null,
    "chatbot": null,
    "knowledge_base": null,
    "url": null
  }
}
destination.type is null on the child, so the scan resolves to the group’s page. A second child in the same group that overrides: 
{
  "object": "qr_code",
  "id": "9e1d4f6a-3b2c-4f5d-8e7a-9c1b2d3e4f5a",
  "public_slug": "xyz9876",
  "group_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "status": "active",
  "destination": {
    "type": "chatbot",
    "chatbot": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "page": null,
    "knowledge_base": null,
    "url": null
  }
}
destination.type is set on the child, so the group is ignored — the scan goes to the chatbot.
To re-attach a broken-out child back to the group’s destination, PATCH the child with destination: { "type": null } (and any companion fields you want cleared). Inheritance resumes on the next scan.

​
CRUD workflow

1

Create the group

POST /qr-groups with a name and (optionally) a shared destination.
curl https://api.awardee.dev/v1/qr-groups \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fall 2024 tabletop run",
    "description": "1000 table cards, all Brunswick venues",
    "status": "active",
    "destination": {
      "type": "page",
      "page": "a1c2e4f6-8b0d-4e2a-9c1b-3d5e7f9a2c4e"
    }
  }'
2

Mint child codes

Codes are minted in the dashboard and tied to the group via group_id. The v1 API is read/update-only for the QR code resource — new codes come from the dashboard.
3

Re-route the whole group

PATCH /qr-groups/{id} and update the destination object. Every inheriting child picks up the change on the next scan.
4

Pause or archive

Flip status on the group to inactive or archived to pause or retire every inheriting child at once.

​
Deleting a group

DELETE /qr-groups/{id} removes the group row. Child codes are not deleted — the database foreign key uses ON DELETE SET NULL, so children have their group_id cleared and stand alone. Their own destinations (if set) take over; inheriting children become unconfigured until you give them their own destination.
Deleting a group can silently break inheriting children if they relied on the group’s destination. Re-route or re-group orphans before deleting.

​
URL params and properties on groups

A group also carries its own static URL params and properties (separate tables: qr_group_url_params, qr_group_properties). At scan time they merge with the child’s params — child overrides on key collision. 
group.url_params  = { utm_campaign: "fall24", utm_medium: "print" }
child.url_params  = { utm_medium: "table" }
merged on scan    = { utm_campaign: "fall24", utm_medium: "table" }
visitor scans with ?utm_source=email
final redirect    = ?utm_campaign=fall24&utm_medium=table&utm_source=email
Live visitor params win over the merged child-then-group baseline.
The v1 API surface focuses on the group resource itself. Group-level URL params and properties remain managed in the dashboard for now. Per-child params and properties are available — see QR Codes sub-resources.

​
Webhook events

EventFires on
qr_group.createdPOST /qr-groups
qr_group.updatedPATCH /qr-groups/{id} or any dashboard edit.
qr_group.deletedDELETE /qr-groups/{id}. Children detach.
Subscribe and verify signatures per the webhooks guide.