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

# Buy labels for many orders

> **Beta** — this endpoint may change before general availability.



## OpenAPI

````yaml /api-reference/openapi.json post /shipping/label-batches
openapi: 3.1.0
info:
  title: Replo Public API
  version: '2026-11-17'
servers:
  - url: https://api.replo.app/v1
security: []
paths:
  /shipping/label-batches:
    post:
      tags:
        - Shipping-label-batches
      summary: Buy labels for many orders
      description: '**Beta** — this endpoint may change before general availability.'
      operationId: shippingLabelBatches.create
      parameters:
        - name: Replo-Api-Version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2026-11-17'
          description: The public API version to use for this request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                projectId:
                  type: string
                  format: uuid
                  description: Project the orders belong to.
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      orderId:
                        type: string
                        format: uuid
                        description: Order to buy a label for.
                      shippingPackageId:
                        type:
                          - string
                          - 'null'
                        format: uuid
                        description: Box to ship in. Omit for the store's default box.
                      weightGrams:
                        type:
                          - integer
                          - 'null'
                        exclusiveMinimum: 0
                        maximum: 70000
                        description: >-
                          Package weight. Omit to add up the item and box
                          weights.
                      service:
                        type:
                          - string
                          - 'null'
                        minLength: 1
                        maxLength: 255
                        description: >-
                          Carrier service code, e.g. "FEDEX_GROUND". Omit for
                          the cheapest service at least as fast as the one the
                          buyer paid for.
                      maxAmount:
                        type:
                          - integer
                          - 'null'
                        minimum: 0
                        description: >-
                          Most to pay for this label, in minor units. A label
                          quoted higher isn't bought and is listed as failed.
                          Omit for no cap.
                    required:
                      - orderId
                  minItems: 1
                  maxItems: 500
                  description: One label per order, for everything not yet shipped.
              required:
                - projectId
                - items
              additionalProperties: false
      responses:
        '201':
          description: Buy labels for many orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingLabelBatch'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerAuth: []
components:
  schemas:
    ShippingLabelBatch:
      type: object
      properties:
        object:
          type: string
          enum:
            - shipping_label_batch
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - purchasing
            - completed
            - partiallyFailed
          description: Labels are bought in the background; poll until done.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ShippingLabel'
        failures:
          type: array
          items:
            type: object
            properties:
              orderId:
                type: string
                format: uuid
              message:
                type: string
            required:
              - orderId
              - message
          description: Orders that got no label, and why.
        createdAt:
          type: string
      required:
        - object
        - id
        - status
        - labels
        - failures
        - createdAt
    ShippingLabel:
      type: object
      properties:
        object:
          type: string
          enum:
            - shipping_label
        id:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        fulfillmentId:
          type:
            - string
            - 'null'
          format: uuid
          description: The package this label ships; null for a return label.
        direction:
          type: string
          enum:
            - outbound
            - return
        carrier:
          type: string
        service:
          type: string
        amount:
          type: integer
          description: Postage paid, in minor units.
        currencyCode:
          type: string
        trackingNumber:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - purchased
            - voidRequested
            - voided
            - voidRejected
        labelUrl:
          type:
            - string
            - 'null'
          description: A short-lived signed link to the label PDF.
        createdAt:
          type: string
      required:
        - object
        - id
        - orderId
        - fulfillmentId
        - direction
        - carrier
        - service
        - amount
        - currencyCode
        - trackingNumber
        - status
        - labelUrl
        - createdAt
    PublicApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            doc_url:
              type: string
            issues:
              type: array
              items:
                type: object
                properties:
                  param:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Dotted path to the failing field within the request body,
                      query or path, e.g. "name" or "variants.0.available"; null
                      when the rule covers the whole input.
                  message:
                    type: string
                    description: Why the field was rejected.
                required:
                  - param
                  - message
              description: >-
                Present on an invalid_request whose input failed validation:
                each failing field and why, at most 10.
          required:
            - code
            - message
            - doc_url
      required:
        - error
  responses:
    InvalidRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    InvalidCredentials:
      description: >-
        Missing or invalid Replo Public API token. Send an active key as
        `Authorization: Bearer replo_sk_...`; if it was revoked, create a new
        key in Replo Settings.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    Forbidden:
      description: >-
        You are not authorized to access this resource. Ask a workspace owner to
        perform this action or to grant the key's creator access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    NotFound:
      description: >-
        Not Found. The resource may not exist, this key may lack the required
        scope, or the key's creator may have lost access. Check the key's scopes
        in Replo Settings and the creator's project or workspace access; a
        workspace owner can grant access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    Conflict:
      description: The resource is in a conflicting state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    PayloadTooLarge:
      description: File content exceeds the 10 MiB limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    RateLimitExceeded:
      description: >-
        Too many requests. Please retry after the time indicated by the
        Retry-After header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    InternalError:
      description: An internal error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    ServiceUnavailable:
      description: Service temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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