Paid value-receipts API

openapi: 3.1.0
info:
  title: API Reference agents value-receipts API
  version: 1.0.0
servers:
- url: https://api.agentpaid.io/api/v1
  description: Production
tags:
- name: value-receipts
paths:
  /value-receipts/sync:
    post:
      operationId: sync-value-receipt
      summary: Sync a value receipt
      description: Find or create a value receipt by natural key (customer + product/order + dates), then populate it with current data inline. Returns the ID, status, and public URL. Posted (sealed) VRs are returned as-is without re-populating.
      tags:
      - value-receipts
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueReceiptSyncResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncValueReceiptRequest'
  /value-receipts/:
    get:
      operationId: list-value-receipts
      summary: List value receipts
      description: List value receipts for the organization
      tags:
      - value-receipts
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
      - name: customerId
        in: query
        description: Filter by customer display ID.
        required: false
        schema:
          type: string
      - name: externalCustomerId
        in: query
        description: Filter by customer external ID.
        required: false
        schema:
          type: string
      - name: orderId
        in: query
        required: false
        schema:
          type: string
      - name: productId
        in: query
        required: false
        schema:
          type: string
      - name: archived
        in: query
        description: Include archived value receipts. Defaults to false.
        required: false
        schema:
          $ref: '#/components/schemas/ValueReceiptsGetParametersArchived'
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueReceiptListResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /value-receipts/{id}:
    get:
      operationId: get-value-receipt-by-id
      summary: Get value receipt
      description: Get a value receipt by ID, including its publish/share state.
      tags:
      - value-receipts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueReceiptDetail'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /value-receipts/{id}/refresh:
    post:
      operationId: refresh-value-receipt
      summary: Refresh a value receipt
      description: Re-populate an existing draft value receipt with current data inline. Returns the slim sync response. Sealed VRs cannot be refreshed.
      tags:
      - value-receipts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueReceiptSyncResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: '409'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /value-receipts/{id}/seal:
    post:
      operationId: seal-value-receipt
      summary: Seal a value receipt
      description: Transition a draft value receipt to sealed (posted) status. Sealed VRs are immutable — they cannot be updated or re-populated.
      tags:
      - value-receipts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: '409'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /value-receipts/{id}/archive:
    post:
      operationId: archive-value-receipt
      summary: Archive a value receipt
      description: Soft-archive a value receipt. Archived VRs are hidden from list by default.
      tags:
      - value-receipts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /value-receipts/{id}/unarchive:
    post:
      operationId: unarchive-value-receipt
      summary: Unarchive a value receipt
      description: Restore an archived value receipt.
      tags:
      - value-receipts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /value-receipts/{id}/publish:
    post:
      operationId: publish-value-receipt
      summary: Publish a value receipt
      description: Make a value receipt publicly accessible via URL.
      tags:
      - value-receipts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueReceiptDetail'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishValueReceiptBody'
  /value-receipts/{id}/unpublish:
    post:
      operationId: unpublish-value-receipt
      summary: Unpublish a value receipt
      description: Revoke public access to a value receipt.
      tags:
      - value-receipts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueReceiptDetail'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties: {}
components:
  schemas:
    SyncValueReceiptRequest:
      type: object
      properties:
        customerId:
          type: string
          description: Mutually exclusive with externalCustomerId. Exactly one is required.
        externalCustomerId:
          type: string
          description: Mutually exclusive with customerId. Exactly one is required.
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        product:
          $ref: '#/components/schemas/SyncValueReceiptRequestProduct'
          description: Mutually exclusive with orderId. Provide at most one.
        orderId:
          type: string
          description: Mutually exclusive with product. Provide at most one.
      required:
      - startDate
      - endDate
      title: SyncValueReceiptRequest
    ValueReceiptSummary:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        publicUrlToken:
          type: string
        publicUrl:
          type: string
          format: uri
        isPublished:
          type: boolean
        customerId:
          type:
          - string
          - 'null'
        customerName:
          type:
          - string
          - 'null'
        customerExternalId:
          type:
          - string
          - 'null'
        orderId:
          type:
          - string
          - 'null'
        productId:
          type:
          - string
          - 'null'
        currency:
          type: string
        startDate:
          type:
          - string
          - 'null'
          format: date-time
        endDate:
          type:
          - string
          - 'null'
          format: date-time
        totalDeliveredValue:
          type:
          - number
          - 'null'
          format: double
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - status
      - publicUrlToken
      - publicUrl
      - isPublished
      - customerId
      - customerName
      - customerExternalId
      - orderId
      - productId
      - currency
      - startDate
      - endDate
      - totalDeliveredValue
      - archivedAt
      - createdAt
      title: ValueReceiptSummary
    ValueReceiptListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ValueReceiptSummary'
        total:
          type: integer
      required:
      - data
      - total
      title: ValueReceiptListResponse
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      title: SuccessResponse
    ValueReceiptsGetParametersArchived:
      type: string
      enum:
      - 'true'
      - 'false'
      default: 'false'
      title: ValueReceiptsGetParametersArchived
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: string
      required:
      - error
      title: ErrorResponse
    ValueReceiptSyncResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        publicUrlToken:
          type: string
        publicUrl:
          type: string
          format: uri
      required:
      - id
      - status
      - publicUrlToken
      - publicUrl
      title: ValueReceiptSyncResponse
    ValueReceiptDetail:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        publicUrlToken:
          type: string
        publicUrl:
          type: string
          format: uri
        isPublished:
          type: boolean
        customerId:
          type:
          - string
          - 'null'
        customerName:
          type:
          - string
          - 'null'
        customerExternalId:
          type:
          - string
          - 'null'
        orderId:
          type:
          - string
          - 'null'
        productId:
          type:
          - string
          - 'null'
        currency:
          type: string
        startDate:
          type:
          - string
          - 'null'
          format: date-time
        endDate:
          type:
          - string
          - 'null'
          format: date-time
        totalDeliveredValue:
          type:
          - number
          - 'null'
          format: double
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        publishedAt:
          type:
          - string
          - 'null'
          format: date-time
        publishExpiresAt:
          type:
          - string
          - 'null'
          format: date-time
        allowEmbed:
          type: boolean
      required:
      - id
      - status
      - publicUrlToken
      - publicUrl
      - isPublished
      - customerId
      - customerName
      - customerExternalId
      - orderId
      - productId
      - currency
      - startDate
      - endDate
      - totalDeliveredValue
      - archivedAt
      - createdAt
      - publishedAt
      - publishExpiresAt
      - allowEmbed
      title: ValueReceiptDetail
    SyncValueReceiptRequestProduct:
      type: object
      properties:
        productId:
          type: string
        currency:
          type: string
      required:
      - productId
      description: Mutually exclusive with orderId. Provide at most one.
      title: SyncValueReceiptRequestProduct
    PublishValueReceiptBody:
      type: object
      properties:
        publishExpiresAt:
          type:
          - string
          - 'null'
          format: date-time
      title: PublishValueReceiptBody
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer