ProsperStack Payments API

openapi: 3.2.0
info:
  title: ProsperStack API Reference Payments API
  version: v1
  description: 'This is the reference documentation for the ProsperStack API v1. Visit ProsperStack at prosperstack.com.


    For more information on ProsperStack features, see the primary documentation.


    Let us know how we can improve the API, documentation or anything else you need help with at support@prosperstack.com.


    # Introduction


    The ProsperStack API provides a REST-like interface to your ProsperStack data. It uses standard HTTP verbs, accepts JSON-encoded request bodies and provides JSON-encoded responses.


    You can use the ProsperStack API to access your live production data or data from test mode. The API key you use to authenticate requests determines which mode will be used.


    # Authentication


    The ProsperStack API uses API keys to authenticate requests. You can manage your API keys from the ProsperStack API Keys settings page.


    Live mode API keys have the prefix `key_` and test mode API keys have the prefix `key_test_`.


    Authentication uses HTTP basic authentication. Provide your API key as the basic authentication username. You don''t need to provide a password.


    A simple example using cURL:


    ```bash

    curl https://api.prosperstack.com/v1/flow_sessions \

    -u key_LSdJXBrN3SP7bdJrQSMp2eZK:

    ```


    Learn more about creating API keys.


    # Pagination


    All list endpoints support cursor-based pagination. The body of a list response will contain a `data` property with an array of objects and a `next_cursor` property desginating the cursor value to retrieve the next set of results.


    Use the value of `next_cursor` in the `cursor` query parameter to specify the set of results to return. If `next_cursor` is `null`, there are no more results.


    You can also specify a `limit` in the query parameters to adjust the number of items per result set. The limit defaults to 10 and has a maximum of 100.


    # Rate limits


    The ProsperStack API enforces a rate limit of 100 requests per minute. Your live mode and test mode accounts have separate limits.


    When the rate limit is exceeded, requests will fail with the HTTP status `429 Too Many Requests` until the limit window resets.


    The ProsperStack API implements the RateLimit Header Fields for HTTP draft which describes a set of HTTP headers you can use to observe current request limits.


    The headers are:


    - `RateLimit-Limit` — The limit of requests per time window (1 minute)

    - `RateLimit-Remaining` — The number of requests left before exceeding the limit

    - `RateLimit-Reset` — The number of seconds until the limit window resets


    If you need to exceed the rate limit, let us know at support@prosperstack.com and we''ll be happy to help.'
  x-logo:
    url: https://prosperstack.com/images/logo-api.svg
servers:
- url: https://api.prosperstack.com/v1
security:
- basicAuth: []
tags:
- name: Payments
  x-displayName: Payments
  description: 'A payment represents a retained payment made by a saved or deflected subscriber.


    Payments can be of type `saved` or `deflected`.'
paths:
  /payments:
    get:
      summary: List payments
      operationId: listPayments
      tags:
      - Payments
      parameters:
      - name: type
        in: query
        description: Filter payments by type
        schema:
          type: string
          enum:
          - saved
          - deflected
      - name: subscriber_id
        in: query
        description: Filter payments by subscriber ID
        schema:
          type: string
      - name: subscription_id
        in: query
        description: Filter payments by subscription ID
        schema:
          type: string
      - name: platform_subscriber_id
        in: query
        description: Filter payments by platform subscriber ID
        schema:
          type: string
      - name: platform_subscription_id
        in: query
        description: Filter payments by platform subscription ID
        schema:
          type: string
      - name: offer_id
        in: query
        description: Filter payments by offer ID
        schema:
          type: string
      - name: paid_at
        in: query
        description: 'Filter payments by the `paid_at` property. Specify as a dictionary with one or more of the following properties:


          - `paid_at[gt]` — Return payments where `paid_at` is greater than this value

          - `paid_at[lt]` — Return payments where `paid_at` is less than this value

          - `paid_at[gte]` — Return payments where `paid_at` is greater than or equal to this value

          - `paid_at[lte]` — Return payments where `paid_at` is less than or equal to this value


          Specify date values in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.

          '
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor to retrieve
        schema:
          type: string
      - name: limit
        in: query
        description: Limit of payments to return
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  next_cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/Error'
  /payments/{id}:
    get:
      summary: Retrieve a payment
      operationId: retrievePaymentById
      tags:
      - Payments
      parameters:
      - name: id
        in: path
        description: Payment ID to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/Error'
        '404':
          description: Not Found
          $ref: '#/components/responses/Error'
components:
  schemas:
    DunningOfferDetails:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - dunning
    CouponOfferDetails:
      type: object
      required:
      - type
      - coupon_type
      - amount_off
      - duration
      - months
      - apply_to
      - platform_coupon_id
      properties:
        type:
          type: string
          enum:
          - coupon
        coupon_type:
          type: string
          enum:
          - percentage
          - fixed
        amount_off:
          type: string
          example: '23.7'
        duration:
          type: string
          enum:
          - once
          - forever
          - repeating
          example: repeating
        months:
          type:
          - number
          - 'null'
          example: 6
        apply_to:
          type: string
          enum:
          - subscription
          - subscriber
        platform_coupon_id:
          type:
          - string
          - 'null'
    TrialExtensionOfferDetails:
      type: object
      required:
      - type
      - days
      properties:
        type:
          type: string
          enum:
          - trial_extension
        days:
          type: number
          example: 14
    Offer:
      type: object
      required:
      - id
      - type
      - goal
      - context
      - name
      - details
      - metadata
      - created_at
      - updated_at
      properties:
        id:
          type: string
          example: offr_jIGqAAUKqWM2pptJTfRuei1t
        type:
          type: string
          enum:
          - change_frequency
          - change_plan
          - coupon
          - custom
          - downgrade
          - dunning
          - free_gift
          - modify_subscription
          - pause_subscription
          - product_swap
          - purchase
          - reactivate
          - reschedule_order
          - trial_extension
          - upgrade
        goal:
          type: string
          enum:
          - retention
          - conversion
          - reactivation
        context:
          type: string
          enum:
          - cancellation_flow
          - conversion_campaign
          - landing_page
        name:
          type: string
          example: 40% off
        details:
          oneOf:
          - $ref: '#/components/schemas/ChangeFrequencyOfferDetails'
          - $ref: '#/components/schemas/ChangePlanOfferDetails'
          - $ref: '#/components/schemas/CouponOfferDetails'
          - $ref: '#/components/schemas/CustomOfferDetails'
          - $ref: '#/components/schemas/DowngradeOfferDetails'
          - $ref: '#/components/schemas/DunningOfferDetails'
          - $ref: '#/components/schemas/FreeGiftOfferDetails'
          - $ref: '#/components/schemas/ModifySubscriptionOfferDetails'
          - $ref: '#/components/schemas/PauseSubscriptionOfferDetails'
          - $ref: '#/components/schemas/ProductSwapOfferDetails'
          - $ref: '#/components/schemas/PurchaseOfferDetails'
          - $ref: '#/components/schemas/ReactivateOfferDetails'
          - $ref: '#/components/schemas/RescheduleOrderOfferDetails'
          - $ref: '#/components/schemas/TrialExtensionOfferDetails'
          - $ref: '#/components/schemas/UpgradeOfferDetails'
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DowngradeOfferDetails:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - downgrade
    Cursor:
      type:
      - string
      - 'null'
      example: 'null'
    ChangeFrequencyOfferDetails:
      type: object
      required:
      - type
      - interval
      - interval_count
      - metadata
      - options
      properties:
        type:
          type: string
          enum:
          - change_frequency
        interval:
          type: string
          enum:
          - day
          - week
          - month
          - year
          example: month
        interval_count:
          type: number
          example: 3
        metadata:
          type: object
        options:
          type: array
          description: All available change-frequency options for this offer
          items:
            type: object
            required:
            - interval
            - interval_count
            - metadata
            properties:
              interval:
                type: string
                enum:
                - day
                - week
                - month
                - year
              interval_count:
                type: number
              metadata:
                type: object
    SubscriberProperty:
      type: object
      required:
      - id
      - key
      - name
      - entity
      - type
      - format
      properties:
        id:
          type: string
          example: prop_jrtpyZs1httwFFIl7V80cHwf
        key:
          type: string
          example: number_of_contacts
        name:
          type: string
          example: Number of contacts
        entity:
          type: string
          enum:
          - subscriber
        type:
          type: string
          enum:
          - text
          - number
          - boolean
          - date
          example: number
        format:
          type:
          - string
          - 'null'
          enum:
          - number
          - currency
          example: number
    ModifySubscriptionOfferDetails:
      type: object
      required:
      - type
      - modifications
      properties:
        type:
          type: string
          enum:
          - modify_subscription
        modifications:
          type: array
          description: Modifications applied to the subscription when the offer is accepted
          items:
            type: object
            required:
            - action
            - platform_plan_id
            properties:
              action:
                type: string
                enum:
                - add_plan
                - remove_plan
                - add_add_on
                - remove_add_on
              platform_plan_id:
                type:
                - string
                - 'null'
                description: Platform-specific identifier of the plan or add-on affected by this modification
    SubscriberPropertyValue:
      type: object
      required:
      - property
      - value
      - formatted_value
      properties:
        property:
          $ref: '#/components/schemas/SubscriberProperty'
        value:
          oneOf:
          - type: string
          - type: string
            format: date
          - type: number
          - type: boolean
          example: 5800
        formatted_value:
          type: string
          example: 5,800
    ReactivateOfferDetails:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - reactivate
    Subscription:
      type: object
      required:
      - id
      - platform_id
      - subscriber_id
      - mrr
      - status
      - properties
      - data
      - created_at
      - updated_at
      properties:
        id:
          type: string
          example: subn_dp79dRR5wIy1kGW4PCO41wit
        platform_id:
          type: string
          example: sub_JE1trB8eUAnh0r
        subscriber_id:
          type: string
          example: subr_GQmXBebvivMb5tHhassNV9kj
        mrr:
          type: string
          example: '399.95'
        status:
          type: string
          enum:
          - active
          - canceled
          - future
          - paused
          - trialing
          example: active
        properties:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionPropertyValue'
        data:
          type: object
          description: Additional data about the subscription from the connected subscription platform
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    UpgradeOfferDetails:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - upgrade
    RescheduleOrderOfferDetails:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - reschedule_order
    PurchaseOfferDetails:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - purchase
    PauseSubscriptionOfferDetails:
      type: object
      required:
      - type
      - interval
      - interval_count
      - pause_at
      - metadata
      - options
      properties:
        type:
          type: string
          enum:
          - pause_subscription
        interval:
          type: string
          enum:
          - day
          - week
          - month
          - indefinitely
          - billing_cycle
          example: month
        interval_count:
          type: number
          example: 3
        pause_at:
          type: string
          enum:
          - immediately
          - period_end
        metadata:
          type: object
        options:
          type: array
          description: All available pause options for this offer
          items:
            type: object
            required:
            - interval
            - interval_count
            - metadata
            properties:
              interval:
                type: string
                enum:
                - day
                - week
                - month
                - indefinitely
                - billing_cycle
              interval_count:
                type: number
              metadata:
                type: object
    ChangePlanOfferDetails:
      type: object
      required:
      - type
      - platform_plan_id
      - prorate
      - platform_coupon_id
      properties:
        type:
          type: string
          enum:
          - change_plan
        platform_plan_id:
          type: string
        prorate:
          type: boolean
        platform_coupon_id:
          type:
          - string
          - 'null'
    Payment:
      type: object
      required:
      - id
      - type
      - amount
      - currency
      - platform_invoice_id
      - subscription
      - subscriber
      - paid_at
      properties:
        id:
          type: string
          example: pay_F1sfjrcEEdYN3ewRsoJdUseY
        type:
          type: string
          enum:
          - saved
          - deflected
        amount:
          type: string
          example: '12.99'
        currency:
          type: string
          example: usd
        platform_invoice_id:
          type: string
          example: in_1RY7koITn5pi3looOluiingP
        platform_invoice_number:
          type: string
          example: '1006'
        subscriber:
          $ref: '#/components/schemas/Subscriber'
        subscription:
          $ref: '#/components/schemas/Subscription'
        offer:
          oneOf:
          - $ref: '#/components/schemas/Offer'
          - type: 'null'
        paid_at:
          type: string
          format: date-time
    ProductSwapOfferDetails:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - product_swap
    SubscriptionPropertyValue:
      type: object
      required:
      - property
      - value
      - formatted_value
      properties:
        property:
          $ref: '#/components/schemas/SubscriptionProperty'
        value:
          oneOf:
          - type: string
          - type: string
            format: date
          - type: number
          - type: boolean
          example: true
        formatted_value:
          type: string
          example: 'True'
    Subscriber:
      type: object
      required:
      - id
      - platform_id
      - name
      - email
      - status
      - properties
      - data
      - created_at
      - updated_at
      properties:
        id:
          type: string
          example: subr_dRiytWmkVtSBt9mOpRaC0ca0
        platform_id:
          type: string
          example: cus_Jax42BBWGOWuDp
        name:
          type: string
          example: Jane Doe
        email:
          type: string
          example: jane@example.com
        status:
          type: string
          enum:
          - active
          - canceled
          - converted
          - deflected
          - inactive
          - reactivated
          - recovered
          - saved
          example: saved
        properties:
          type: array
          items:
            $ref: '#/components/schemas/SubscriberPropertyValue'
        data:
          type: object
          description: Additional data about the subscriber from the connected subscription platform
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SubscriptionProperty:
      type: object
      required:
      - id
      - key
      - name
      - entity
      - type
      - format
      properties:
        id:
          type: string
          example: prop_S6A17y8S8wgKBBJbveQHpLW6
        key:
          type: string
          example: is_professional
        name:
          type: string
          example: Is professional
        entity:
          type: string
          enum:
          - subscription
        type:
          type: string
          enum:
          - text
          - number
          - boolean
          - date
          example: boolean
        format:
          type:
          - string
          - 'null'
          enum:
          - number
          - currency
          example: 'null'
    CustomOfferDetails:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - custom
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    FreeGiftOfferDetails:
      type: object
      required:
      - type
      - platform_variant_id
      properties:
        type:
          type: string
          enum:
          - free_gift
        platform_variant_id:
          type:
          - string
          - 'null'
          description: Platform-specific identifier of the product variant offered as the free gift
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic