openapi: 3.0.3
info:
  title: parcelLab Campaigns Events API
  description: 'parcelLab API v4 Enhanced — the REST API for the parcelLab post-purchase

    experience platform. Send orders and trackings, retrieve order status,

    look up pickup/drop-off locations, predict delivery dates, manage return

    registrations and configurations, evaluate marketing campaigns, and

    publish surveys to your customers.


    Regional base URLs are available for EU and US workloads in addition to

    the global endpoint.

    '
  version: '4'
  contact:
    name: parcelLab Developer Support
    url: https://docs.parcellab.com/docs/developers/readme
  license:
    name: Proprietary
    url: https://parcellab.com/legal/terms-of-service/
servers:
- url: https://api.parcellab.com
  description: Global production endpoint
- url: https://api.eu.parcellab.com
  description: EU regional endpoint
- url: https://api.us.parcellab.com
  description: US regional endpoint
security:
- parcellabApiToken: []
tags:
- name: Events
  description: Send custom shop or warehouse events into the tracking timeline.
paths:
  /v4/track/events/:
    post:
      tags:
      - Events
      summary: Send Shop or Warehouse Event
      operationId: sendShopEvent
      description: Push a custom event/checkpoint (e.g., warehouse pick, pack, dispatch) into the order timeline. Identifies the order by courier+tracking, account+reference, or account+order_number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShopEvent'
      responses:
        '204':
          description: Event accepted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: Invalid payload or query parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ShopEvent:
      type: object
      required:
      - event_timestamp
      - event_status
      properties:
        event_timestamp:
          type: string
          format: date-time
        event_status:
          type: string
        location:
          type: string
        event_details:
          type: string
        placeholder_value:
          type: string
        courier:
          type: string
        tracking_number:
          type: string
        account:
          type: integer
        reference_number:
          type: string
        order_number:
          type: string
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        errors:
          type: object
          additionalProperties: true
  securitySchemes:
    parcellabApiToken:
      type: apiKey
      in: header
      name: Authorization
      description: '`Authorization: Parcellab-API-Token <base64(account_id:token)>`. App- generated tokens may instead use the `Bearer <token>` scheme.'