openapi: "3.0.3"
info:
  title: JVZoo API
  version: "all"
  description: |
    The REST APIs provide programmatic access to data in JVZoo.com. With JVZoo's API you can retrieve Transaction Summaries, Affiliate Status, Recurring Payment Information, and much more. The REST API identifies JVZoo Applications using Basic Auth; responses are in JSON.

    ## About this view

    This is the **combined view** — every endpoint across every released version is listed below, each tagged with the version it belongs to. If you want to see a single version in isolation, use the version selector in the top right.

    | Version | Base URL | Status |
    |---------|----------|--------|
    | **v3.0** | `https://api.jvzoo.com/v3.0` | Current — new LTV-focused transactions endpoints |
    | **v2.1** | `https://api.jvzoo.com/v2.1` | Supported — richer transaction details + affiliate management |
    | **v2.0** | `https://api.jvzoo.com/v2.0` | Supported — original endpoints; some paths replaced by v2.1 equivalents but still functional |

    When a newer version offers similar functionality at a **different URL**, the older endpoint includes a **See also** link in its description. These are not deprecations — every listed endpoint is fully supported. An endpoint is only marked `deprecated` if a newer version replaces it at the **exact same URL**.

    Each operation below displays a version badge (**v3.0** / **v2.1** / **v2.0**) in its summary. The full URL for any operation is `https://api.jvzoo.com` + the path shown (the version prefix is already part of the path).

    ## Requests (Authorization)

    All requests sent to the JVZoo REST API need to be authenticated with a valid API Key over HTTPS. This is to prevent unauthorized access to your account through the API.

    > ⚠️ **Caution**
    > Your API Key grants full access to your JVZoo account including personal, financial and sensitive information — **keep these values secret**.

    To obtain an API key, go to [https://www.jvzoo.com/account/applications](https://www.jvzoo.com/account/applications) and create a new API Application under the My Account tab.

    Once created, your API key for the active app will be shown under Vendor Applications at [http://www.jvzoo.com/account/applications/index](http://www.jvzoo.com/account/applications/index).

    In the examples below, replace `MyAPIKeyString` with your API Key. **Note:** leave `x` in the password portion.

    **Example Command Line Code:**
    ```
    curl -u MyAPIKeyString:x https://api.jvzoo.com/v3.0/transactions?start_date=2025-01-01&end_date=2025-01-31
    ```

    ## Responses

    For ease of use, we have adopted a common response envelope for ALL API calls. Custom headers and the set of attributes do not change from call to call — **only the values of the attributes and the content of the *results* array are different from call to call**.

    ### Custom Headers

    Every response includes a custom header `X-API-Version` indicating which API version served the request.

    ```
    HTTP/1.0 200 OK
    X-API-Version: 3.0
    Content-Type: application/json
    ```

    ### Sample Response Envelope

    ```json
    {
      "meta": {
        "status": {
          "http_status_code": 200,
          "code": 2000,
          "message": "Success",
          "detail": null
        },
        "results_count": 1,
        "api_version": "3.0"
      },
      "results": [ ... ]
    }
    ```

    | Name | Location | Description |
    |------|----------|-------------|
    | Meta | `meta` | Metadata describing the response. |
    | Status | `meta.status` | The response status. |
    | HTTP Status Code | `meta.status.http_status_code` | Industry-standard three-digit HTTP status code. |
    | Code | `meta.status.code` | JVZoo internal four-digit code. |
    | Message | `meta.status.message` | Short message describing the result. |
    | Detail | `meta.status.detail` | Additional detail, or null. |
    | Result Count | `meta.results_count` | Number of result items returned. |
    | API Version | `meta.api_version` | The version of the API that served the request. |
    | Results | `results` | The payload — always an array. |

    ## HTTP Status Codes

    | Response | Meaning |
    |----------|---------|
    | 200 | Success |
    | 204 | Request yielded no content |
    | 400 | Bad Request — parameter may be wrong |
    | 401 | Unauthorized — bad/missing/invalid API key |
    | 402 | Request Failed — parameters correct |
    | 403 | Request Refused — user does not have access |
    | 404 | Not Found |
    | 405 | Method not allowed |
    | 429 | Too Many Requests |
    | 500 | Internal Server Error |

    ## Response Codes

    | Code | Meaning |
    |------|---------|
    | 2000 | Success |
    | 2040 | No content found |
    | 4000 | Bad Request |
    | 4001 | Invalid Parameters |
    | 4010 | API Key is missing |
    | 4011 | Invalid API Key present |
    | 4012 | Authenticated user does not have access (specific) |
    | 4030 | Authenticated user does not have access (general) |
    | 4031 | Authenticated user does not have access (forbidden) |
    | 4040 | Not found |
    | 4050 | Method not allowed |
    | 4290 | Too many requests |
    | 5000 | Internal Server Error |

    ## Payment Statuses

    | Code | Meaning |
    |------|---------|
    | Unpaid | Payment is currently being held. |
    | Payment Error | Error while trying to make the payment. Not recoverable. |
    | Paid | Payment was paid successfully. |
    | Refunded | Payment was successfully refunded. |

servers:
  - url: https://api.jvzoo.com

security:
  - basicAuth: []

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your API Key as the username and `x` as the password.

  schemas:
    MetaStatus:
      type: object
      properties:
        http_status_code:
          type: integer
          example: 200
        code:
          type: integer
          example: 2000
        message:
          type: string
          example: "Success"
        detail:
          type: string
          nullable: true
          example: null

    # ----- v3.0 schemas -----

    Pagination:
      type: object
      properties:
        page_size:
          type: integer
          description: Number of results per page
          example: 50
        page_index:
          type: integer
          description: Current zero-based page index
          example: 0
        has_more:
          type: boolean
          description: Whether more pages are available
          example: true

    Customer:
      type: object
      properties:
        email:
          type: string
          example: "larry@smith.com"
        first_name:
          type: string
          example: "Larry"
        last_name:
          type: string
          example: "Smith"

    Affiliate:
      type: object
      nullable: true
      description: The affiliate credited with the sale, or null if there was no affiliate on the transaction.
      properties:
        id:
          type: integer
          description: The affiliate's user ID
          example: 98765
        display_name:
          type: string
          nullable: true
          description: The affiliate's display name
          example: "Joe Affiliate"

    Tracking:
      type: object
      description: |
        Tracking data associated with the transaction. Includes:
          - Vendor pass-through values from the checkout URL (`vtid`, `custom`).
          - Click attribution captured at the time of the click that led to the sale (UTM parameters, sub-IDs, ad-platform click IDs, and any other query-string parameters in `other_params`).

        All fields are nullable; when no click attribution was captured (e.g., direct traffic), the click attribution fields will all be null.
      properties:
        vtid:
          type: string
          nullable: true
          description: Vendor Tracking ID (vtid) supplied by the vendor at checkout.
          example: "blackfriday"
        custom:
          type: string
          nullable: true
          description: Vendor-supplied custom pass-through value from the checkout URL.
          example: "source=fb&campaign=42"
        tid:
          type: string
          nullable: true
          description: Affiliate-set tracking ID captured at click time.
          example: "fb-campaign-42"
        utm_source: { type: string, nullable: true, example: "facebook" }
        utm_medium: { type: string, nullable: true, example: "cpc" }
        utm_campaign: { type: string, nullable: true, example: "blackfriday2025" }
        utm_content: { type: string, nullable: true, example: "hero-banner" }
        utm_term: { type: string, nullable: true, example: "weight-loss" }
        sub_id1: { type: string, nullable: true, example: "creative-A" }
        sub_id2: { type: string, nullable: true, example: null }
        sub_id3: { type: string, nullable: true, example: null }
        sub_id4: { type: string, nullable: true, example: null }
        sub_id5: { type: string, nullable: true, example: null }
        gclid: { type: string, nullable: true, description: "Google Ads click identifier.", example: "Cj0KCQiA..." }
        fbclid: { type: string, nullable: true, description: "Facebook/Meta Ads click identifier.", example: "IwAR1..." }
        msclkid: { type: string, nullable: true, description: "Microsoft Advertising (Bing) click identifier.", example: null }
        ttclid: { type: string, nullable: true, description: "TikTok Ads click identifier.", example: null }
        li_fat_id: { type: string, nullable: true, description: "LinkedIn first-party Ad Tracking identifier.", example: null }
        twclid: { type: string, nullable: true, description: "X (formerly Twitter) Ads click identifier.", example: null }
        yclid: { type: string, nullable: true, description: "Yandex click identifier.", example: null }
        other_params:
          type: string
          nullable: true
          description: Any additional query string parameters captured at click time (raw string; format not guaranteed).
          example: "source=newsletter&ref=jan25"

    Payouts:
      type: object
      description: Financial breakdown of the transaction. All values are strings formatted to 2 decimal places.
      properties:
        seller_earnings: { type: string, description: "Net earnings to the vendor after all fees and commissions", example: "48.50" }
        affiliate_payout: { type: string, description: "Commission amount paid to the affiliate", example: "38.80" }
        agent_payout: { type: string, description: "Commission amount paid to the sales agent", example: "0.00" }
        jv_payout: { type: string, description: "Commission amount paid to JV partners", example: "0.00" }
        jvzoo_fee: { type: string, description: "JVZoo platform fee", example: "9.70" }

    Refund:
      type: object
      description: Refund details. All impact values are negative, representing amounts clawed back.
      properties:
        refund_date: { type: string, description: "Date and time of the refund in ISO 8601 format", example: "2025-01-20T14:00:00+00:00" }
        refund_amount: { type: string, description: "Total amount refunded to the customer", example: "97.00" }
        seller_refund_impact: { type: string, description: "Amount clawed back from the vendor (negative)", example: "-48.50" }
        affiliate_refund_impact: { type: string, description: "Amount clawed back from the affiliate (negative)", example: "-38.80" }
        agent_refund_impact: { type: string, description: "Amount clawed back from the agent (negative)", example: "0.00" }
        jv_refund_impact: { type: string, description: "Amount clawed back from JV partners (negative)", example: "0.00" }
        jvzoo_fee_adjustment: { type: string, description: "JVZoo fee adjustment on refund (negative)", example: "-9.70" }

    Transaction:
      type: object
      description: A complete transaction record with financial breakdown.
      properties:
        transaction_id: { type: string, description: "The payKey identifier for the transaction", example: "AP-1234567890ABCDEFG" }
        sale_date: { type: string, description: "Date and time of the original sale in ISO 8601 format", example: "2025-01-15T14:30:00+00:00" }
        product_id: { type: integer, description: "The numeric product ID", example: 123456 }
        product_name: { type: string, description: "The product name at time of sale", example: "My Product" }
        amount: { type: string, description: "Total transaction amount (2 decimal places)", example: "97.00" }
        status: { type: string, description: "Transaction status (e.g., settled)", example: "settled" }
        customer:
          $ref: "#/components/schemas/Customer"
        affiliate:
          $ref: "#/components/schemas/Affiliate"
        tracking:
          $ref: "#/components/schemas/Tracking"
        payouts:
          $ref: "#/components/schemas/Payouts"
        refund:
          nullable: true
          description: Refund details, or null if the transaction has not been refunded
          allOf:
            - $ref: "#/components/schemas/Refund"

    # ----- v2.1 schemas -----

    AffiliateStatusV21:
      type: object
      properties:
        created: { type: string, description: "GMT time of creation", example: "2014-07-31T19:06:11+00:00" }
        product_id: { type: integer, description: "Product id", example: 123456 }
        affiliate_id: { type: integer, description: "Affiliate id", example: 12345 }
        comments: { type: string, description: "Request comment if any submitted", example: "My Test Comments" }
        status: { type: string, description: "Status of the approval request. Values: REQUESTED, APPROVED, DENIED", example: "APPROVED" }
        custom_commission: { type: integer, description: "The percentage payout for the commissions. 75 = 75% commission", example: 75 }
        delayed_commission: { type: boolean, description: "Is the affiliate on Delayed Commission Payments?", example: false }
        custom_sales_page_url: { type: string, nullable: true, description: "Custom sales page url.", example: null }
        custom_payment_1st_payout: { type: integer, description: "Custom payout for the 1st payment", example: 10 }
        custom_payment_trial_payout: { type: integer, description: "Custom payout for the trial period", example: 15 }

    AffiliateStatusUpdateRequest:
      type: object
      required:
        - approval_status
      properties:
        approval_status: { type: string, description: "Status of the approval request. Accepted Values: INSTANT, DELAYED, DENIED", example: "INSTANT" }
        custom_commission: { type: integer, description: "[Optional] The percentage payout for the commissions. 75 = 75% commission", example: 75 }
        custom_sales_page_url: { type: string, description: "[Optional] Custom sales page url just for this affiliate's traffic", example: "http://domain.com" }
        affiliate_verification_email: { type: string, description: "[Optional] Email of the affiliate you are trying to edit. Optional sanity check.", example: "test@domain.com" }
        custom_payment_1st_payout: { type: integer, description: "[Optional] Custom payout amount for the 1st payment", example: 10 }
        custom_payment_trial_payout: { type: integer, description: "[Optional] Custom payout amount for the trial period", example: 15 }

    TransactionPayoutV21:
      type: object
      properties:
        payee_amount: { type: string, example: "100.00" }
        payee_user_id: { type: string, example: "123" }
        payee_name: { type: string, example: "John Doe" }
        payout_type: { type: string, example: "VENDOR" }
        payment_processor: { type: string, example: "PayPal with JVZooPay" }
        payout_status: { type: string, example: "Paid" }

    TransactionDetailV21:
      type: object
      properties:
        date: { type: string, example: "2024-01-01 12:00:00" }
        product_name: { type: string, example: "Your Product Name" }
        product_id: { type: string, example: "123456" }
        status: { type: string, example: "COMPLETED" }
        total: { type: string, example: "100.00" }
        pre_key: { type: string, nullable: true, example: null }
        tid: { type: string, nullable: true, example: null }
        vtid: { type: string, nullable: true, example: null }
        tax_total: { type: string, example: "0.00" }
        international_sales_tax: { type: number, example: 0 }
        national_sales_tax: { type: number, example: 0 }
        vat_tax: { type: number, example: 0 }
        shipping_fee: { type: string, example: "0.000000" }
        paypal_email: { type: string, example: "jane@doe.com" }
        vendor_id: { type: string, example: "1" }
        vendor_name: { type: string, example: "John Doe" }
        vendor_email: { type: string, example: "john@doe.com" }
        affiliate_id: { type: string, example: "123" }
        affiliate_name: { type: string, example: "BBC Systems, Inc." }
        affiliate_email: { type: string, example: "bbcsystemsinc.com@gmail.com" }
        customer_first_name: { type: string, example: "Larry" }
        customer_last_name: { type: string, example: "Smith" }
        customer_email: { type: string, example: "larry@smith.com" }
        customer_ip: { type: string, example: "1.1.1.1" }
        customer_phone: { type: string, example: "+9995551234" }
        delivery_name: { type: string, example: "Larry Smith" }
        delivery_phone: { type: string, example: "" }
        delivery_address_line_1: { type: string, example: "123 Main Street" }
        delivery_address_line_2: { type: string, example: "" }
        delivery_city: { type: string, example: "Anytown" }
        delivery_region: { type: string, example: "CA" }
        delivery_postal_code: { type: string, example: "12345" }
        delivery_country: { type: string, example: "UNITED_STATES" }
        transactionPayouts:
          type: array
          items:
            $ref: "#/components/schemas/TransactionPayoutV21"

    # ----- v2.0 schemas -----

    AffiliateStatusV20:
      type: object
      properties:
        created: { type: string, example: "2014-07-31T19:06:11+00:00" }
        product_id: { type: integer, example: 123456 }
        affiliate_id: { type: string, example: "12345" }
        comments: { type: string, example: "My Test Comments" }
        status_id: { type: integer, example: 2 }
        custom_commission: { type: string, example: "0.75" }
        delayed_commission: { type: string, example: "0" }

    RecurringPaymentCancel:
      type: object
      properties:
        canceled: { type: boolean, example: true }

    RecurringPaymentStatus:
      type: object
      properties:
        id: { type: integer, example: 123456 }
        status: { type: string, example: "ACTIVE" }
        current_payments: { type: integer, example: 6 }
        max_number_of_payments: { type: integer, example: 13 }
        max_total_of_all_payments: { type: string, example: "37.00" }
        max_amount_per_payment: { type: string, example: "3.00" }
        next_payment: { type: string, example: "3.00" }
        paypal_email: { type: string, example: "email@domain.com" }
        contact_email: { type: string, example: "email@domain.com" }
        code: { type: string, nullable: true, example: null }
        price: { type: string, example: "3.00" }
        payment_period: { type: integer, example: 1 }
        payment_count: { type: integer, example: 12 }
        payment_first_payout: { type: string, example: "0.25" }
        has_payment_trial: { type: boolean, example: true }
        payment_trial_price: { type: string, example: "1.00" }
        payment_trial_period: { type: integer, example: 3 }
        payment_trial_payout: { type: string, example: "0.5" }
        payout: { type: string, nullable: true, example: null }
        current_payments_amount: { type: string, example: "16.00" }
        created: { type: string, example: "2015-06-19T13:12:44+00:00" }
        preKey: { type: string, example: "PA-1234567890ABCDEFG" }
        sender_email: { type: string, example: "email@domain.com" }
        last_date: { type: string, example: "2015-10-23T04:00:00+00:00" }
        next_date: { type: string, example: "2015-11-23T05:00:00+00:00" }
        ip: { type: string, example: "1.1.1.1" }
        referrer: { type: string, example: "https://www.domain.com" }
        tid: { type: string, nullable: true, example: null }
        vtid: { type: string, nullable: true, example: null }
        product_id: { type: integer, example: 123456 }

    TransactionSummaryV20:
      type: object
      properties:
        transaction_id: { type: string, example: "AP-1234567890ABCDEFG" }
        date: { type: string, example: "2014-12-19T12:49:16+00:00" }
        product_name: { type: string, example: "My Product" }
        product_id: { type: integer, example: 123456 }
        status: { type: string, example: "COMPLETED" }
        price: { type: string, example: "0.75" }
        first_name: { type: string, example: "Joe" }
        last_name: { type: string, example: "Smith" }
        paypal_email: { type: string, example: "email@domain.com" }

    AffiliateTransactionV20:
      type: object
      properties:
        transaction_id: { type: string, example: "AP-1234567890ABCDEFG" }
        date: { type: string, example: "2016-12-18T08:09:15+00:00" }
        product_name: { type: string, example: "Example Product Name" }
        product_id: { type: integer, example: 123456 }
        status: { type: string, example: "COMPLETED" }
        price: { type: string, example: "0.01" }
        customer_email: { type: string, example: "email@domain.com" }
        ip: { type: string, example: "1.1.1.1" }
        first_name: { type: string, example: "Joe" }
        last_name: { type: string, example: "Smith" }
        affiliate_commission: { type: string, example: "0.01" }
        affiliate_commission_status: { type: string, example: "UNPAID" }
        affiliate_id: { type: integer, example: 1 }
        affiliate_name: { type: string, example: "Jane Doe" }

    LatestTransactionV20:
      type: object
      properties:
        transaction_id: { type: string, example: "AP-1234567890ABCDEFG" }
        date: { type: string, example: "2016-12-02T12:50:30+00:00" }
        product_name: { type: string, example: "Example Product Name" }
        product_id: { type: integer, example: 123456 }
        status: { type: string, example: "COMPLETED" }
        price: { type: string, example: "27.00" }
        customer_email: { type: string, example: "email@domain.com" }
        ip: { type: string, example: "1.1.1.1" }
        first_name: { type: string, example: "Joe" }
        last_name: { type: string, example: "Le Feuvre" }
        affiliate_id: { type: integer, example: 1 }
        affiliate_name: { type: string, example: "John Doe" }

tags:
  - name: Transactions
    description: Transaction data retrieval — summaries, details, and LTV-oriented breakdowns.
  - name: Affiliate Status
    description: Details of an affiliate's relationship with a particular product.
  - name: Affiliate Stats
    description: Statistics for a particular affiliate for a particular product.
  - name: Products
    description: Product information.
  - name: Recurring Payments
    description: Recurring payment management.

paths:

  # =========================================================================
  # v3.0
  # =========================================================================

  /v3.0/transactions:
    get:
      tags: [Transactions]
      summary: "[v3.0] List Transactions"
      x-badges:
        - name: "v3.0"
          color: green
      operationId: listTransactionsV3
      description: |
        Returns a paginated list of transactions for the authenticated vendor within the specified date range.

        **Pagination:** Use `page_size` and `page_index` to paginate through results. Check `meta.pagination.has_more` to determine if additional pages exist.

        **Date filtering:** Transactions are included if their sale date OR refund date falls within the specified range. This ensures that a transaction refunded in January will appear in a January query even if the original sale was in December.
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          example: "2025-01-01"
          description: Start date in ISO 8601 format (e.g., 2025-01-01).
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          example: "2025-01-31"
          description: End date in ISO 8601 format. Must be greater than or equal to start_date.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 200
          description: Number of results per page. Default 50, max 200.
        - name: page_index
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Zero-based page index.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version:
              schema:
                type: string
              example: "3.0"
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status:
                        $ref: "#/components/schemas/MetaStatus"
                      results_count: { type: integer, example: 2 }
                      api_version: { type: string, example: "3.0" }
                      total_count: { type: integer, description: "Total number of transactions matching the query", example: 150 }
                      pagination:
                        $ref: "#/components/schemas/Pagination"
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Transaction"

  /v3.0/transactions/{transaction_id}:
    get:
      tags: [Transactions]
      summary: "[v3.0] Retrieve Transaction Details"
      x-badges:
        - name: "v3.0"
          color: green
      operationId: getTransactionV3
      description: Returns the full details for a single transaction. The authenticated user must be the vendor (seller) for the requested transaction.
      parameters:
        - name: transaction_id
          in: path
          required: true
          schema:
            type: string
          example: "AP-1234567890ABCDEFG"
          description: The payKey identifier for the transaction.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version:
              schema:
                type: string
              example: "3.0"
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status:
                        $ref: "#/components/schemas/MetaStatus"
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "3.0" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Transaction"
        "404":
          description: Transaction not found or user is not the vendor

  # =========================================================================
  # v2.1
  # =========================================================================

  /v2.1/affiliates/{affiliate_id}/products/{product_id}:
    get:
      tags: [Affiliate Status]
      summary: "[v2.1] Retrieve an Affiliate Status"
      x-badges:
        - name: "v2.1"
          color: blue
      operationId: getAffiliateStatusV21
      description: Returns the details of a specific affiliate relationship for the specified product.
      parameters:
        - name: affiliate_id
          in: path
          required: true
          schema: { type: integer }
          example: 12345
          description: The ID of the affiliate.
        - name: product_id
          in: path
          required: true
          schema: { type: integer }
          example: 123456
          description: The ID of the product.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.1" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "2.1" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/AffiliateStatusV21"
    put:
      tags: [Affiliate Status]
      summary: "[v2.1] Add or Update an Affiliate Status"
      x-badges:
        - name: "v2.1"
          color: blue
      operationId: putAffiliateStatusV21
      description: Adds or updates an Affiliate Status (relationship). Returns the latest version of the Affiliate Status.
      parameters:
        - name: affiliate_id
          in: path
          required: true
          schema: { type: integer }
          example: 12345
        - name: product_id
          in: path
          required: true
          schema: { type: integer }
          example: 123456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AffiliateStatusUpdateRequest"
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.1" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "2.1" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/AffiliateStatusV21"

  /v2.1/affiliatestats/{affiliate_id}/products/{product_id}:
    get:
      tags: [Affiliate Stats]
      summary: "[v2.1] Retrieve Affiliate Stats"
      x-badges:
        - name: "v2.1"
          color: blue
      operationId: getAffiliateStatsV21
      description: Returns the detailed stats for a specific affiliate for a specific product.
      parameters:
        - name: affiliate_id
          in: path
          required: true
          schema: { type: integer }
          example: 12345
        - name: product_id
          in: path
          required: true
          schema: { type: integer }
          example: 123456
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.1" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "2.1" }
                  results:
                    type: array
                    items:
                      type: object

  /v2.1/products/names:
    get:
      tags: [Products]
      summary: "[v2.1] Get Product Names"
      x-badges:
        - name: "v2.1"
          color: blue
      operationId: getProductNamesV21
      description: Returns a list of product names.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.1" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 4 }
                      api_version: { type: string, example: "2.1" }
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        product_id: { type: integer, example: 123456 }
                        product_name: { type: string, example: "Test Product #1" }

  /v2.1/transaction/details/{paykey}:
    get:
      tags: [Transactions]
      summary: "[v2.1] Transaction Details"
      x-badges:
        - name: "v2.1"
          color: blue
      operationId: getTransactionDetailsV21
      description: Returns the details for the specified transaction id.
      parameters:
        - name: paykey
          in: path
          required: true
          schema: { type: string }
          example: "AP-1234567890ABCDEFG"
          description: The transaction id used for the transaction.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.1" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "2.1" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/TransactionDetailV21"

  # =========================================================================
  # v2.0
  # =========================================================================

  /v2.0/products/{product_id}/affiliates/{affiliate_id}:
    get:
      tags: [Affiliate Status]
      summary: "[v2.0] Retrieve an Affiliate Status"
      description: |
        Returns the details of a specific affiliate relationship for the specified product.

        **See also:** v2.1's [`GET /v2.1/affiliates/{affiliate_id}/products/{product_id}`](#tag/Affiliate-Status) returns an updated response shape at a different URL.
      x-badges:
        - name: "v2.0"
          color: gray
      operationId: getAffiliateStatusV20
      parameters:
        - name: product_id
          in: path
          required: true
          schema: { type: integer }
          example: 1
          description: The ID of the product.
        - name: affiliate_id
          in: path
          required: true
          schema: { type: integer }
          example: 1
          description: The ID of the affiliate.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.0" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "2.0" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/AffiliateStatusV20"

  /v2.0/recurring_payment/{preKey}:
    put:
      tags: [Recurring Payments]
      summary: "[v2.0] Cancel a Recurring Payment"
      x-badges:
        - name: "v2.0"
          color: gray
      operationId: cancelRecurringPaymentV20
      description: Cancels a recurring payment for the specified PreKey.
      parameters:
        - name: preKey
          in: path
          required: true
          schema: { type: string }
          example: "PA-1234567890ABCDEFG"
          description: The key used for that payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, example: "CANCEL" }
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.0" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "2.0" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/RecurringPaymentCancel"
    get:
      tags: [Recurring Payments]
      summary: "[v2.0] Recurring Payment Status"
      x-badges:
        - name: "v2.0"
          color: gray
      operationId: getRecurringPaymentStatusV20
      description: Returns the status of a recurring payment for the PreKey specified.
      parameters:
        - name: preKey
          in: path
          required: true
          schema: { type: string }
          example: "PA-1234567890ABCDEFG"
          description: The key used for that payment.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.0" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "2.0" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/RecurringPaymentStatus"

  /v2.0/transactions/summaries/{paykey}:
    get:
      tags: [Transactions]
      summary: "[v2.0] Transaction Summaries"
      description: |
        Returns a summary for the specified transaction id.

        **See also:** v2.1's [`GET /v2.1/transaction/details/{paykey}`](#tag/Transactions) returns a richer, more detailed response at a different URL.
      x-badges:
        - name: "v2.0"
          color: gray
      operationId: getTransactionSummariesV20
      parameters:
        - name: paykey
          in: path
          required: true
          schema: { type: string }
          example: "AP-1234567890ABCDEFG"
          description: The key used for that transaction.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.0" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 1 }
                      api_version: { type: string, example: "2.0" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/TransactionSummaryV20"

  /v2.0/latest-affiliates-transactions/{paykey}:
    get:
      tags: [Transactions]
      summary: "[v2.0] Get Affiliate Transactions"
      x-badges:
        - name: "v2.0"
          color: gray
      operationId: getLatestAffiliatesTransactionsV20
      description: |
        Retrieve transactions made by you as an affiliate.

        **Limitations:**
        - Will only return 100 at a time.
      parameters:
        - name: paykey
          in: path
          required: false
          schema: { type: string }
          example: "AP-1234567890ABCDEFG"
          description: If a payKey is provided it will use that as the starting point to select from — it will not be included in the results. If not provided the results will start at the oldest transactions starting 90 days ago.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.0" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 2 }
                      api_version: { type: string, example: "2.0" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/AffiliateTransactionV20"

  /v2.0/latest-transactions/{paykey}:
    get:
      tags: [Transactions]
      summary: "[v2.0] Get Latest Transactions"
      description: |
        Retrieve latest transactions of all of your products.

        **Limitations:**
        - Will only return 100 at a time.

        **See also:** v3.0's [`GET /v3.0/transactions`](#tag/Transactions) provides paginated, date-filtered access with richer financial breakdowns at a different URL.
      x-badges:
        - name: "v2.0"
          color: gray
      operationId: getLatestTransactionsV20
      parameters:
        - name: paykey
          in: path
          required: false
          schema: { type: string }
          example: "AP-1234567890ABCDEFG"
          description: If a payKey is provided it will use that as the starting point to select from — it will not be included in the results. If not provided the results will start at the oldest transactions.
      responses:
        "200":
          description: Success
          headers:
            X-API-Version: { schema: { type: string }, example: "2.0" }
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status: { $ref: "#/components/schemas/MetaStatus" }
                      results_count: { type: integer, example: 3 }
                      api_version: { type: string, example: "2.0" }
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/LatestTransactionV20"