2D Barcodes

2D Barcodes are QR Codes that contain a GS1-compliant URL. The URL is composed of both a standard destination that users will be taken to when scanning the QR Code with their phones as well as product information that barcode scanners can read, such as the product's GTIN number. Our 2D Barcodes use bitlinks for the destination so that you get all the benefits of our links platform and GS1-compliant 2D Barcodes.

Creating a 2D Barcode

This process is very similar to creating a standard QR Code, but with GS1 keys added in the request body.

This is an example request to create a standard QR Code for an existing Bitlink:

POST /v4/qr-codes

{
  "title": "Standard QR Code",
  "group_guid": "Ba1bc23dE4F",
  "destination": {
    "bitlink_id": "bit.ly/3KbTdQr"
  }
}

To change this to a 2D Barcode request, simply add values under the "gs1" property:

POST /v4/qr-codes

{
  "title": "2D Barcode QR Code",
  "group_guid": "Ba1bc23dE4F",
  "destination": {
    "bitlink_id": "bit.ly/3KbTdQr"
  },
  "gs1": {
    "values": [
      {
        "key": "01",
        "value": "44556679"
      }
    ]
  }
}

A successful response will return the QR Code's ID for the 2D Barcode, which can be used to fetch more information, like the barcode's image:

{
  "qrcode_id": "Qo95fOaDycKPJEz",
  "group_guid": "Ba1bc23dE4F",
  "title": "2D Barcode QR Code",
  "archived": false,
  "created": "2024-09-05T15:24:36Z",
  "updated": "2024-09-05T15:24:36Z"
}

The GS1 key used in the request is a GTIN in its numerical form, 01, with an 8-digit value of 44556679. For consistency, all GS1 keys should be in their numerical form. If the GTIN's value is not a 14-digit number, it will be automatically padded with 0s at the start to make it 14-digits. In this example, 44556679 would become 00000044556679 in the generated GS1-compliant URL. This is done to comply with GS1 syntax requirements (see section 4.1 of the digital link standards).

Currently, our API only supports GTIN values.

Customizing a 2D Barcode

The same visual customizations for standard QR Codes are also available for 2D Barcodes. Refer to the Create Endpoint for a detailed breakdown of the customizations that are available. QR Code colors and file type options may be available depending on your subscription plan.

As an example, the 2D Barcode from above could have been created with a rounded dot pattern and leaf shaped corners with this request:

POST /v4/qr-codes

{
  "title": "2D Barcode QR Code",
  "group_guid": "Ba1bc23dE4F",
  "destination": {
    "bitlink_id": "bit.ly/3KbTdQr"
  },
  "gs1": {
    "values": [
      {
        "key": "01",
        "value": "44556679"
      }
    ]
  },
  "render_customizations": {
    "dot_pattern_type": "rounded",
    "corners": {
      "corner_1": { "shape": "leaf" },
      "corner_2": { "shape": "leaf" },
      "corner_3": { "shape": "leaf" }
    }
  }
}

The barcode's customization can also be updated like a standard QR Code using a PATCH request. For example, the first 2D Barcode created above with the ID Qo95fOaDycKPJEz could have been updated with the same dot pattern and corner shapes with this request:

PATCH /v4/qr-codes/Qo95fOaDycKPJEz

{
  "title": "2D Barcode QR Code",
  "render_customizations": {
    "dot_pattern_type": "rounded",
    "corners": {
      "corner_1": { "shape": "leaf" },
      "corner_2": { "shape": "leaf" },
      "corner_3": { "shape": "leaf" }
    }
  }
}

A successful response will return the same metadata about the QR Code as when it was created.

{
  "qrcode_id": "Qo95fOaDycKPJEz",
  "group_guid": "Ba1bc23dE4F",
  "title": "2D Barcode QR Code",
  "archived": false,
  "created": "2024-09-05T15:24:36Z",
  "updated": "2024-09-05T19:00:42Z"
}