> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a barcode

> Create a PNG or SVG barcode through your configured AvraAPI Barcode Generator.

Generate a barcode image for an order reference, product code, or other compatible value. The response is always PNG or SVG media; there is no Base64 JSON response mode for this operation.

The Playground returns an image response for both supported formats. Generated artifacts are real and can consume Development-project credits.

<Info>
  **Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
</Info>

## API endpoint

```text title="POST" theme={null}
https://avraapi.com/api/v1/utilities/barcode/generate
```

## Request fields

| Field | Required | Rules |
| - | - | - |
| `data` | Yes | Value to encode; 1–80 characters. The selected barcode type can impose additional character or length rules. |
| `type` | No | `C128` (default), `C128A`, `C128B`, `C128C`, `EAN13`, `EAN8`, `UPCA`, `UPCE`, `C39`, `C39+`, `I25`, `ITF14`, `MSI`, or `POSTNET`. |
| `format` | No | `png` (default) or `svg`. |
| `width_factor` | No | Number from 1 to 4; default `2`. The generator converts the value to an integer, so use whole numbers when you need predictable bar width. |
| `height` | No | Height from 20 to 300 pixels; default `80`. |
| `color` | No | Six-digit hex colour, with or without `#`; default black (`000000`). |
| `privacy_mode` | No | Boolean request-level privacy setting. Use `X-Privacy-Mode: 1` for the shared privacy control. |

`C128` is the default general-purpose type. Select a retail, postal, numeric, or constrained variant only when your downstream scanner or standard requires it. AvraAPI validates the public type name, while the barcode renderer enforces any type-specific encoding constraint.

## Request example

```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/utilities/barcode/generate" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "Accept: image/png" \
  --header "Content-Type: application/json" \
  --data '{
    "data": "ORDER-2026-001",
    "type": "C128",
    "format": "png",
    "width_factor": 2,
    "height": 80,
    "color": "0450ff"
  }' \
  --output order-barcode.png
```

## Media response

For `png`, the success body is the barcode image with `Content-Type: image/png`. For `svg`, it is SVG media with `Content-Type: image/svg+xml`. Both return `Content-Length`, `Cache-Control: no-store`, `Content-Disposition: inline`, and `X-APIX-Request-ID` headers.

The response body is not JSON. Save the media response or send it into your own image workflow. If you need a Base64 string, convert the returned media in your backend rather than expecting a separate API response mode.

## Error codes

| HTTP | `error.code` | When it happens | What to do |
| - | - | - | - |
| `400` | <span style={{ whiteSpace: 'nowrap' }}><code>http\_error</code></span> | The barcode renderer rejected the supplied data for the selected barcode type. | Use data compatible with the chosen type, or select a different type. |
| `401` | <span style={{ whiteSpace: 'nowrap' }}><code>unauthorized</code></span> | Credentials are missing, invalid, inactive, or do not match `X-ENV`. | Check your backend credential configuration. |
| `402` | <span style={{ whiteSpace: 'nowrap' }}><code>insufficient\_funds</code></span> | The selected Barcode Generator integration requires credits that are unavailable. | Check the project balance and service configuration. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>validation\_failed</code></span> | A field is missing or outside its documented input rules. | Correct the body using the field details in the response. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>provider\_selection\_failed</code></span> | No active Barcode Generator integration can be selected for the project environment. | Enable or configure the Barcode Generator integration. |
| `429` | <span style={{ whiteSpace: 'nowrap' }}><code>rate\_limit\_exceeded</code></span> | The configured request limit was reached. | Respect `Retry-After` when present. |
| `500` | <span style={{ whiteSpace: 'nowrap' }}><code>internal\_error</code></span> | The generator could not complete unexpectedly. | Retain the request ID and retry only when appropriate. |
| `503` | <span style={{ whiteSpace: 'nowrap' }}><code>project\_paused</code></span> | The project is paused. | Reactivate the project before retrying. |

See the [REST API guide](/api-reference/rest-api) for shared credentials, privacy, and response-handling rules.

## Playground resources

The generated reference below lists this endpoint's API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.


## OpenAPI

````yaml api-reference/provider-api.openapi.yaml POST /utilities/barcode/generate
openapi: 3.0.3
info:
  title: AvraAPI Provider API
  version: 1.0.0
  description: >-
    The reviewed public contract for AvraAPI provider services. Operations are
    added to this document only after their route, validation, response,
    privacy, usage, and public-safety contracts have been verified.
servers:
  - url: https://avraapi.com/api/v1
    description: AvraAPI REST API v1
security:
  - ApiKeyHeader: []
    ApiSecretHeader: []
tags:
  - name: Currency
    description: Currency codes, exchange rates, and conversion.
  - name: SMS
    description: Messaging operations through configured AvraAPI providers.
  - name: Security
    description: IP and email security checks.
  - name: Location
    description: IP geolocation and intelligence.
  - name: Utilities
    description: QR code, barcode, and PDF generation.
paths:
  /utilities/barcode/generate:
    post:
      tags:
        - Utilities
      summary: Generate a barcode
      description: >-
        Generates a PNG or SVG barcode through the active Barcode Generator
        integration. The response is always image media; this operation has no
        Base64 JSON output mode.
      operationId: generateBarcode
      parameters:
        - $ref: '#/components/parameters/XEnvironmentHeader'
        - $ref: '#/components/parameters/AcceptJsonHeader'
        - $ref: '#/components/parameters/XPrivacyModeHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BarcodeGenerateRequest'
            examples:
              code_128_png:
                summary: Code 128 PNG barcode
                value:
                  data: ORDER-2026-001
                  type: C128
                  format: png
                  width_factor: 2
                  height: 80
                  color: 0450ff
      responses:
        '200':
          description: Barcode image in the requested format.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/UtilitiesBadRequest'
        '401':
          $ref: '#/components/responses/UtilitiesUnauthorized'
        '402':
          $ref: '#/components/responses/UtilitiesInsufficientFunds'
        '422':
          $ref: '#/components/responses/UtilitiesUnprocessable'
        '429':
          $ref: '#/components/responses/UtilitiesRateLimited'
        '500':
          $ref: '#/components/responses/UtilitiesInternalError'
        '503':
          $ref: '#/components/responses/UtilitiesUnavailable'
components:
  parameters:
    XEnvironmentHeader:
      name: X-ENV
      in: header
      required: false
      description: >-
        Selects the Development credential environment. The Documentation
        Playground exposes Development values only; normal backend integrations
        may use their documented Production credentials outside this tool.
      schema:
        type: string
        enum:
          - dev
          - development
        default: development
    AcceptJsonHeader:
      name: Accept
      in: header
      required: false
      description: Requests a JSON response where the selected operation supports JSON.
      schema:
        type: string
        example: application/json
    XPrivacyModeHeader:
      name: X-Privacy-Mode
      in: header
      required: false
      description: >-
        Optional privacy override. Turn this on to request that AvraAPI suppress
        request-payload storage in observability logs for this request.
      schema:
        type: boolean
        default: false
        example: true
  schemas:
    BarcodeGenerateRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: string
          minLength: 1
          maxLength: 80
          description: >-
            Value to encode. The selected barcode type can impose additional
            content rules.
          x-default: ORDER-2026-001
        type:
          type: string
          enum:
            - C128
            - C128A
            - C128B
            - C128C
            - EAN13
            - EAN8
            - UPCA
            - UPCE
            - C39
            - C39+
            - I25
            - ITF14
            - MSI
            - POSTNET
          default: C128
          x-default: C128
        format:
          type: string
          enum:
            - png
            - svg
          default: png
          x-default: png
        width_factor:
          type: number
          minimum: 1
          maximum: 4
          default: 2
          x-default: 2
          description: >-
            Bar-width multiplier. The implementation converts this value to an
            integer.
        height:
          type: integer
          minimum: 20
          maximum: 300
          default: 80
          x-default: 80
          description: Barcode height in pixels.
        color:
          type: string
          pattern: ^#?[0-9a-fA-F]{6}$
          default: '000000'
          x-default: '000000'
        privacy_mode:
          type: boolean
          description: >-
            Optional request-level privacy setting. X-Privacy-Mode is the
            universal header override.
    ApiErrorEnvelope:
      type: object
      required:
        - success
        - request_id
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        request_id:
          type: string
          format: uuid
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable error summary.
            details:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
              description: Field-level validation messages when available.
        meta:
          type: object
          description: Some infrastructure errors include additional diagnostic metadata.
          additionalProperties: true
  headers:
    RequestIdHeader:
      description: AvraAPI request identifier for support and troubleshooting.
      schema:
        type: string
        format: uuid
    RetryAfterHeader:
      description: Seconds to wait before retrying a rate-limited request.
      schema:
        type: integer
        minimum: 0
  responses:
    UtilitiesBadRequest:
      description: >-
        The generator could not process an otherwise valid request, such as an
        unsupported barcode payload or an unreachable QR logo URL.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            http_error:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000025
                error:
                  code: http_error
                  message: The generator could not process the supplied input.
                meta: {}
    UtilitiesUnauthorized:
      description: >-
        Missing, invalid, inactive, or environment-mismatched project
        credentials.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            unauthorized:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000026
                error:
                  code: unauthorized
                  message: Project credentials were not accepted.
                meta: {}
    UtilitiesInsufficientFunds:
      description: >-
        The selected Utility integration requires credits that are not
        available.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            insufficient_funds:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000027
                error:
                  code: insufficient_funds
                  message: The selected Utility integration has insufficient credits.
                meta: {}
    UtilitiesUnprocessable:
      description: >-
        The request body is invalid, or the matching Utility integration cannot
        be resolved for the project environment.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            validation_failed:
              summary: Request validation error
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000022
                error:
                  code: validation_failed
                  message: Validation failed.
                  details:
                    data:
                      - The data field is required.
            unavailable_provider:
              summary: Utility provider is not available
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000023
                error:
                  code: provider_selection_failed
                  message: >-
                    No active generator integration is available for this
                    project environment.
    UtilitiesRateLimited:
      description: The configured request limit has been reached.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
        Retry-After:
          $ref: '#/components/headers/RetryAfterHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            rate_limit_exceeded:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000029
                error:
                  code: rate_limit_exceeded
                  message: The request limit has been reached.
                meta: {}
    UtilitiesInternalError:
      description: The Utility operation could not complete unexpectedly.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            internal_error:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000028
                error:
                  code: internal_error
                  message: The Utility operation could not complete.
                meta: {}
    UtilitiesUnavailable:
      description: The project is paused.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            project_paused:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000024
                error:
                  code: project_paused
                  message: This project is currently paused.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your Development project's Client ID. Enter your own value in the
        Documentation Playground.
    ApiSecretHeader:
      type: apiKey
      in: header
      name: X-API-SECRET
      description: >-
        Your Development project's Client Secret. Mintlify does not proxy these
        requests; the browser sends them directly to AvraAPI. Never enter a
        Production secret in the Documentation Playground.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.