openapi: "3.0.3"
info:
  title: JVZoo API
  version: "3.0"
  description: |
    The REST APIs provides 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.

    API v3.0 introduces a new **Transactions** endpoint designed for LTV (Lifetime Value) calculations, with explicit financial breakdowns requiring no downstream calculations.

    ## Requests (Authorization)

    All requests sent to the JVZoo REST API need to be authenticated with valid a 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, you first need go to [https://www.jvzoo.com/account/applications](https://www.jvzoo.com/account/applications) to 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).

    We will use this API Key to verify your identity on each API call you make. The URL of the JVZoo API v3.0 is:

    ```
    https://api.jvzoo.com/v3.0
    ```

    In the examples below, simply replace `MyAPIKeyString` with your API Key and put in the full api url. **Note:** leave `x` in the password portion.

    **Example Command Line Code:**
    ```
    curl -u MyAPIKeyString:x https://api.jvzoo.com/v3.0
    ```

    ## Responses

    For ease of use and simplicity for the developers that integrate with our API, we have adopted a common response 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 has the default headers, however we also include a custom header `X-API-Version` in all responses to make it easier to debug.

    ```
    HTTP/1.0 200 OK
    Date: Fri, 30 Oct 2015 10:26:52 GMT
    X-API-Version: 3.0
    Cache-Control: no-cache
    Content-Length: 162
    Connection: close
    Content-Type: application/json
    ```

    ### Sample Response

    ```json
    {
      "meta": {
        "status": {
          "http_status_code": 200,
          "code": 2000,
          "message": "Success",
          "detail": null
        },
        "results_count": 1,
        "api_version": "3.0"
      },
      "results": [
        {
          "id": 1,
          "name": "John Doe",
          "age": 23,
          "birthday": "1991-10-18"
        }
      ]
    }
    ```

    | Name | Location | Description |
    |------|----------|-------------|
    | Meta | `meta` | A set of data that describes and gives information about other data. |
    | Status | `meta.status` | The response data from the request. |
    | HTTP Status Codes | `meta.status.http_status_code` | Industry standard three digit http status codes. |
    | Code | `meta.status.code` | JVZoo internal four digit code. |
    | Message | `meta.status.message` | Message from the request in basic terms. |
    | Detail | `meta.status.detail` | Details from the request. Default is NULL. |
    | Result Count | `meta.results_count` | Number of result arrays returned. |
    | API Version | `meta.api_version` | The called version of the API. |
    | Results | `results` | The results given from the request. Always an array. |

    ## HTTP Status Codes

    | Response | Meaning |
    |----------|---------|
    | 200 | Success |
    | 204 | Request yielded no content |
    | 400 | Bad Request - Parameter may be wrong |
    | 401 | Unauthorized Request - Bad request, API key missing, or invalid API key |
    | 402 | Request Failed - Parameters correct |
    | 403 | Request Refused - User does not have access |
    | 404 | Not Found |
    | 405 | Request Refused - 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. |

    ## Changes from v2.1

    - New paginated Transaction List endpoint with date range filtering
    - New Transaction Details endpoint with explicit financial breakdowns
    - Payouts broken out into: seller_earnings, affiliate_payout, agent_payout, jv_payout, jvzoo_fee
    - Refund impact data with per-party clawback amounts
    - Nested customer object
    - Affiliate details (id, display_name) on each transaction
    - Tracking data on each transaction: vendor pass-through (vtid, custom) plus full click attribution (UTMs, sub-IDs, ad-platform click IDs)
    - Pagination metadata with total_count and has_more

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

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

    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
          description: Vendor/affiliate-defined sub-ID slot 1.
          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"

tags:
  - name: Transactions
    description: |
      Transaction data retrieval with explicit financial breakdowns for LTV calculations.

      **New in v3.0:** Paginated list endpoint with date range filtering, nested payout breakdowns, and refund impact data.

paths:
  /transactions:
    get:
      tags:
        - Transactions
      summary: List Transactions
      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 (e.g., 2025-01-31). 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"
              example:
                meta:
                  status:
                    http_status_code: 200
                    code: 2000
                    message: "Success"
                    detail: null
                  results_count: 2
                  api_version: "3.0"
                  total_count: 150
                  pagination:
                    page_size: 50
                    page_index: 0
                    has_more: true
                results:
                  - transaction_id: "AP-1234567890ABCDEFG"
                    sale_date: "2025-01-15T14:30:00+00:00"
                    product_id: 123456
                    product_name: "My Product"
                    amount: "97.00"
                    status: "settled"
                    customer:
                      email: "larry@smith.com"
                      first_name: "Larry"
                      last_name: "Smith"
                    affiliate:
                      id: 98765
                      display_name: "Joe Affiliate"
                    tracking:
                      vtid: "blackfriday"
                      custom: "source=fb&campaign=42"
                      tid: "fb-campaign-42"
                      utm_source: "facebook"
                      utm_medium: "cpc"
                      utm_campaign: "blackfriday2025"
                      utm_content: "hero-banner"
                      utm_term: null
                      sub_id1: "creative-A"
                      sub_id2: null
                      sub_id3: null
                      sub_id4: null
                      sub_id5: null
                      gclid: null
                      fbclid: "IwAR1abcXYZ"
                      msclkid: null
                      ttclid: null
                      li_fat_id: null
                      twclid: null
                      yclid: null
                      other_params: null
                    payouts:
                      seller_earnings: "48.50"
                      affiliate_payout: "38.80"
                      agent_payout: "0.00"
                      jv_payout: "0.00"
                      jvzoo_fee: "9.70"
                    refund: null
                  - transaction_id: "AP-9876543210ZYXWVUT"
                    sale_date: "2025-01-10T09:15:00+00:00"
                    product_id: 123456
                    product_name: "My Product"
                    amount: "97.00"
                    status: "settled"
                    customer:
                      email: "jane@doe.com"
                      first_name: "Jane"
                      last_name: "Doe"
                    affiliate: null
                    tracking:
                      vtid: null
                      custom: null
                      tid: null
                      utm_source: null
                      utm_medium: null
                      utm_campaign: null
                      utm_content: null
                      utm_term: null
                      sub_id1: null
                      sub_id2: null
                      sub_id3: null
                      sub_id4: null
                      sub_id5: null
                      gclid: null
                      fbclid: null
                      msclkid: null
                      ttclid: null
                      li_fat_id: null
                      twclid: null
                      yclid: null
                      other_params: null
                    payouts:
                      seller_earnings: "48.50"
                      affiliate_payout: "38.80"
                      agent_payout: "0.00"
                      jv_payout: "0.00"
                      jvzoo_fee: "9.70"
                    refund:
                      refund_date: "2025-01-20T14:00:00+00:00"
                      refund_amount: "97.00"
                      seller_refund_impact: "-48.50"
                      affiliate_refund_impact: "-38.80"
                      agent_refund_impact: "0.00"
                      jv_refund_impact: "0.00"
                      jvzoo_fee_adjustment: "-9.70"
        "400":
          description: Bad Request - Missing or invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status:
                        $ref: "#/components/schemas/MetaStatus"
                      results_count:
                        type: integer
                      api_version:
                        type: string
                  results:
                    type: array
                    items: {}
              example:
                meta:
                  status:
                    http_status_code: 400
                    code: 4001
                    message: "Invalid Parameters"
                    detail: null
                  results_count: 0
                  api_version: "3.0"
                results:
                  - null

  /transactions/{transaction_id}:
    get:
      tags:
        - Transactions
      summary: Retrieve Transaction Details
      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"
              example:
                meta:
                  status:
                    http_status_code: 200
                    code: 2000
                    message: "Success"
                    detail: null
                  results_count: 1
                  api_version: "3.0"
                results:
                  - transaction_id: "AP-1234567890ABCDEFG"
                    sale_date: "2025-01-15T14:30:00+00:00"
                    product_id: 123456
                    product_name: "My Product"
                    amount: "97.00"
                    status: "settled"
                    customer:
                      email: "larry@smith.com"
                      first_name: "Larry"
                      last_name: "Smith"
                    affiliate:
                      id: 98765
                      display_name: "Joe Affiliate"
                    tracking:
                      vtid: "blackfriday"
                      custom: "source=fb&campaign=42"
                      tid: "fb-campaign-42"
                      utm_source: "facebook"
                      utm_medium: "cpc"
                      utm_campaign: "blackfriday2025"
                      utm_content: "hero-banner"
                      utm_term: null
                      sub_id1: "creative-A"
                      sub_id2: null
                      sub_id3: null
                      sub_id4: null
                      sub_id5: null
                      gclid: null
                      fbclid: "IwAR1abcXYZ"
                      msclkid: null
                      ttclid: null
                      li_fat_id: null
                      twclid: null
                      yclid: null
                      other_params: null
                    payouts:
                      seller_earnings: "48.50"
                      affiliate_payout: "38.80"
                      agent_payout: "0.00"
                      jv_payout: "0.00"
                      jvzoo_fee: "9.70"
                    refund: null
        "404":
          description: Transaction not found or user is not the vendor
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status:
                        $ref: "#/components/schemas/MetaStatus"
                      results_count:
                        type: integer
                      api_version:
                        type: string
                  results:
                    type: array
                    items: {}
              example:
                meta:
                  status:
                    http_status_code: 404
                    code: 4040
                    message: "Not found"
                    detail: null
                  results_count: 0
                  api_version: "3.0"
                results:
                  - null