# Purchase Placement Test

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v2/placement-tests/purchase:
    post:
      summary: Purchase Placement Test
      deprecated: false
      description: >-
        Run placement tests on selected mailboxes. Supports two payment modes:


        - MONTHLY: Uses credits from active subscriptions (no additional charge)

        - ONE_TIME: Pay-per-test at $2 per mailbox (wallet payment)


        Tests can be run on specific mailboxes or filtered by tags, status, and
        search terms.
      tags:
        - placement test
      parameters:
        - name: x-auth-zapmail
          in: header
          description: ''
          required: true
          example: ''
          schema:
            type: string
        - name: x-workspace-key
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
        - name: x-service-provider
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                placementType:
                  type: string
                testName:
                  type: string
                mailboxIds:
                  type: array
                  items:
                    type: string
              required:
                - placementType
                - testName
                - mailboxIds
              x-apidog-orders:
                - placementType
                - testName
                - mailboxIds
            example:
              placementType: ONE_TIME
              testName: Campaign Deliverability Check
              mailboxIds:
                - 02ff3709-831d-4920-945a-6d36e3c8f3e7
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      checkoutUrl:
                        type: string
                      checkoutSession:
                        type: boolean
                      walletUsed:
                        type: boolean
                      cartOrderId:
                        type: string
                      testName:
                        type: string
                      placementType:
                        type: string
                      mailboxCount:
                        type: integer
                      totalCost:
                        type: integer
                      currency:
                        type: string
                      invoice:
                        type: object
                        properties:
                          invoiceId:
                            type: string
                          invoiceUrl:
                            type: string
                          status:
                            type: string
                        required:
                          - invoiceId
                          - invoiceUrl
                          - status
                        x-apidog-orders:
                          - invoiceId
                          - invoiceUrl
                          - status
                      walletBalance:
                        type: object
                        properties:
                          previousBalance:
                            type: integer
                          amountDeducted:
                            type: integer
                          currentBalance:
                            type: integer
                        required:
                          - previousBalance
                          - amountDeducted
                          - currentBalance
                        x-apidog-orders:
                          - previousBalance
                          - amountDeducted
                          - currentBalance
                      testOrders:
                        type: array
                        items:
                          type: object
                          properties:
                            orderId:
                              type: string
                            mailboxEmail:
                              type: string
                            status:
                              type: string
                          required:
                            - orderId
                            - mailboxEmail
                            - status
                          x-apidog-orders:
                            - orderId
                            - mailboxEmail
                            - status
                      estimatedCompletionTime:
                        type: string
                    required:
                      - checkoutUrl
                      - checkoutSession
                      - walletUsed
                      - cartOrderId
                      - testName
                      - placementType
                      - mailboxCount
                      - totalCost
                      - currency
                      - invoice
                      - walletBalance
                      - testOrders
                      - estimatedCompletionTime
                    x-apidog-orders:
                      - checkoutUrl
                      - checkoutSession
                      - walletUsed
                      - cartOrderId
                      - testName
                      - placementType
                      - mailboxCount
                      - totalCost
                      - currency
                      - invoice
                      - walletBalance
                      - testOrders
                      - estimatedCompletionTime
                required:
                  - status
                  - message
                  - data
                x-apidog-orders:
                  - status
                  - message
                  - data
              example:
                status: 200
                message: Payment link
                data:
                  checkoutUrl: https://invoice.stripe.com/i/acct_xxx
                  checkoutSession: false
                  walletUsed: true
          headers: {}
          x-apidog-name: Success
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        msg:
                          type: string
                        param:
                          type: string
                        location:
                          type: string
                      x-apidog-orders:
                        - msg
                        - param
                        - location
                required:
                  - status
                  - message
                  - errors
                x-apidog-orders:
                  - status
                  - message
                  - errors
              example:
                status: 400
                message: Validation failed
                errors:
                  - msg: placementType must be MONTHLY or ONE_TIME
                    param: placementType
                    location: body
          headers: {}
          x-apidog-name: Bad Request
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  message:
                    type: string
                  errorId:
                    type: string
                required:
                  - status
                  - message
                  - errorId
                x-apidog-orders:
                  - status
                  - message
                  - errorId
              example:
                status: 401
                message: Invalid API key
                errorId: uuid-v4-error-id
          headers: {}
          x-apidog-name: Unauthorized
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  message:
                    type: string
                  errorId:
                    type: string
                required:
                  - status
                  - message
                  - errorId
                x-apidog-orders:
                  - status
                  - message
                  - errorId
              example:
                status: 500
                message: Internal server error
                errorId: uuid-v4-error-id
          headers: {}
          x-apidog-name: Internal Server Error
      security: []
      x-apidog-folder: placement test
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797058/apis/api-25780176-run
components:
  schemas: {}
  securitySchemes: {}
servers:
  - url: https://api.zapmail.ai/api
    description: Prod Env
security: []

```