Tackle Subscriptions API

openapi: 3.0.3
info:
  title: Tackle Authentication Subscriptions API
  description: Authenticated programmatic access to Tackle's webhooks, metering, private offers, and more.
  version: 1.0.0
  contact:
    name: Tackle Support
    email: support@tackle.io
    url: https://tackle.io
servers:
- url: https://api.tackle.io
tags:
- name: Subscriptions
  description: Operations for Subscriptions
paths:
  /v1/subscriptions:
    get:
      summary: List Subscriptions
      tags:
      - Subscriptions
      responses:
        '200':
          $ref: '#/components/responses/Subscriptions_200-OK-Subscriptions'
        '401':
          $ref: '#/components/responses/401-Unauthorized-MTM'
      operationId: v1-list-subscriptions
      description: List all subscriptions, optionally filtered by search criteria
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/productid_query'
      - $ref: '#/components/parameters/customerid'
      - $ref: '#/components/parameters/clouds'
      - $ref: '#/components/parameters/Start_date'
      - $ref: '#/components/parameters/End_date'
  /v1/subscriptions/{tackle_subscription_id}:
    parameters:
    - $ref: '#/components/parameters/tackle_subscription_id'
    get:
      summary: Get a Subscription
      tags:
      - Subscriptions
      responses:
        '200':
          $ref: '#/components/responses/Subscriptions_200-OK-Subscription'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '404':
          $ref: '#/components/responses/Subscriptions_404-Not-Found-Subscription'
      operationId: v1-get-subscription
      description: Gets more detailed information for a specific subscription
      security:
      - BearerAuth: []
components:
  schemas:
    TimestampZeroUtcOffsetOptional:
      type: string
      description: Optional ISO format timestamp with zero UTC offset
      example: '2021-10-25T21:38:20.865Z'
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d*)?Z$
      format: date-time
      nullable: true
    AwsCustomerId:
      type: string
      description: AWS Account Reference ID
      example: ij3sXMkN3or
      minLength: 0
    SubscriptionLink:
      type: string
      title: SubscriptionLink
      description: A URL for a given subscription resource
      format: uri
    CustomerId:
      anyOf:
      - $ref: '#/components/schemas/AwsCustomerId'
      - $ref: '#/components/schemas/GcpCustomerId'
      - $ref: '#/components/schemas/AzureCustomerId'
      - $ref: '#/components/schemas/RedHatCustomerId'
    TimestampZeroUtcOffset:
      type: string
      description: ISO format timestamp with zero UTC offset
      example: '2021-10-25T21:38:20.865Z'
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d*)?Z$
      format: date-time
    RedHatCustomerId:
      type: string
      description: Red Hat Customer Id
      example: 615334398743ac63d55cc4db
      minLength: 0
    SubscriptionId:
      type: string
      description: Subscription Id
      example: 5fd2a7e8908e88888c7f0e71
      minLength: 0
      nullable: true
    RedHatCloud:
      type: string
      description: Red Hat Cloud
      default: redhat
      enum:
      - redhat
      example: redhat
    AwsMarketplaceData:
      type: object
      properties:
        data:
          type: object
          properties:
            CustomerAWSAccountId:
              title: CustomerAWSAccountId
              type: string
              description: AWS account ID associated to the customerid for the individual customer
              example: example-account-id
      description: Marketplace data specific to AWS
      title: AWS
    RedHatSubscriptionRenewType:
      type: string
      description: Renew Type
      enum:
      - ORIGINAL_TERM
      - TERMINATE
      example: ORIGINAL_TERM
    RedHatTermUnit:
      type: string
      description: The unit for the term
      enum:
      - DAYS
      - WEEKS
      - MONTHS
      - YEARS
      example: MONTHS
    AwsCloud:
      type: string
      description: AWS Cloud
      default: aws
      enum:
      - aws
      example: aws
    GcpEntitlement:
      type: object
      description: A purchase entitlement from GCP Marketplace
      properties:
        account:
          type: string
          description: The resource name of the account that this entitlement is based on, if any
        consumers:
          type: array
          description: The resources using this entitlement, if applicable
          items:
            type: string
        createTime:
          type: string
          format: date-time
          example: '2020-10-02T15:01:23.045123456Z'
        messageToUser:
          type: string
          description: Provider-supplied message that is displayed to the end user
        name:
          type: string
          description: The resource name of the entitlement
        newPendingPlan:
          type: string
          description: The identifier of the pending new plan, required if the product has plans and the entitlement has a pending plan change
        offer:
          type: string
        offerEndTime:
          type: string
          format: date-time
        plan:
          type: string
          description: The identifier of the plan that was procured, required if the product has plans
        product:
          type: string
          description: The identifier of the product that was procured
        provider:
          type: string
          description: The identifier of the service provider that this entitlement was created against
        productExternalName:
          type: string
        quoteExternalName:
          type: string
        state:
          type: string
          description: The state of the entitlement
        subscriptionEndTime:
          type: string
        updateTime:
          type: string
          format: date-time
          example: '2019-10-25T21:38:20.865Z'
        usageReportingId:
          type: string
          description: The consumerId to use when reporting usage through the Service Control API. See the consumerId field at Reporting Metrics for more details. This field is present only if the product has usage-based billing configured.
      required:
      - account
      - createTime
      - name
      - plan
      - product
      title: GcpEntitlement
    IsFreeTrial:
      type: boolean
      description: Designation for Free Trial
      example: false
      default: false
      readOnly: true
    ProductLink:
      type: string
      title: ProductLink
      description: A URL for a given product resource
      format: uri
    SubscriptionDetails:
      type: object
      properties:
        entitlements:
          $ref: '#/components/schemas/Entitlements'
        registration_details:
          $ref: '#/components/schemas/RegistrationDetails'
        marketplace_data:
          $ref: '#/components/schemas/MarketplaceData'
    OtherMarketplaceData:
      description: GCP, Azure, and Red Hat do not currently have marketplace specific data
      type: object
      title: GCP, Azure, or Red Hat
    AzureCustomerId:
      type: string
      description: Azure Subscription ID
      example: 1b3gs3f4-2794-abcd-3fa3-063ga0s3t3re
      minLength: 0
    Error:
      title: ErrorResponse
      type: object
      properties:
        code:
          type: string
          description: Error code
          minLength: 0
        error:
          type: string
          description: Error response
          minLength: 0
        errors:
          description: Error details
          type: array
          items: {}
        error_type:
          type: string
          enum:
          - service_exception
          - client_exception
      required:
      - code
      - error
      - errors
    AzureEntitlement:
      type: object
      description: A purchase entitlement from Azure Marketplace
      properties:
        plan:
          type: string
        quantity:
          type: integer
        subscription_id:
          type: string
        subscription_name:
          type: string
        offer_id:
          type: string
      required:
      - plan
      - quantity
      - subscription_id
      - subscription_name
      - offer_id
    Metadata:
      title: Metadata
      type: object
      description: Metadata for a given request
      properties:
        link:
          type: string
          format: uri
          example: https://api.tackle.io
      required:
      - link
    AwsEntitlement:
      properties:
        dimension:
          type: string
        skuid:
          type: string
        expiration:
          type: string
          format: date-time
          example: '2019-04-24T12:23:03.048000+00:00'
        value:
          type: integer
      required:
      - dimension
      - skuid
      - expiration
      - value
      example:
        dimension: example_dimension_name
        expiration: '2019-04-24T12:23:03.048000+00:00'
        skuid: example_awsdimension_apiname_1
        value: 1
      description: 'A purchase entitlement from AWS Marketplace '
    SubscriptionItem:
      type: object
      properties:
        link:
          $ref: '#/components/schemas/SubscriptionLink'
    AwsProductId:
      type: string
      description: AWS Product Code
      example: 1test1a2b3c4d5e6f7g8h9ijk
      minLength: 0
    ListSubscriptionsResponse:
      title: ListSubscriptionsResponse
      type: object
      description: Response describing data containing a list of subscriptions and additional response metadata
      properties:
        data:
          type: array
          description: A list of Subscriptions
          items:
            $ref: '#/components/schemas/SubscriptionContracted'
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
      - data
      - metadata
    Subscription:
      type: object
      properties:
        tackle_subscription_id:
          $ref: '#/components/schemas/SubscriptionId'
        productid:
          $ref: '#/components/schemas/ProductId'
        product_link:
          $ref: '#/components/schemas/ProductLink'
        cloud:
          $ref: '#/components/schemas/Clouds'
        customerid:
          $ref: '#/components/schemas/CustomerId'
        offerid:
          $ref: '#/components/schemas/OfferId'
        created_at:
          $ref: '#/components/schemas/TimestampZeroUtcOffset'
        registered_at:
          $ref: '#/components/schemas/TimestampZeroUtcOffsetOptional'
        cancelled_at:
          $ref: '#/components/schemas/TimestampZeroUtcOffsetOptional'
        updated_at:
          $ref: '#/components/schemas/TimestampZeroUtcOffset'
        started_at:
          $ref: '#/components/schemas/TimestampZeroUtcOffset'
        ended_at:
          $ref: '#/components/schemas/TimestampZeroUtcOffset'
        is_free_trial:
          $ref: '#/components/schemas/IsFreeTrial'
      required:
      - tackle_subscription_id
      - productid
      - customerid
      - created_at
    GcpCustomerId:
      type: string
      description: GCP External Account ID
      example: E-ABC2-D330-E2FG-H2Q2
      minLength: 0
    Entitlement:
      description: A purchase entitlement for a given cloud marketplace
      oneOf:
      - $ref: '#/components/schemas/AwsEntitlement'
      - $ref: '#/components/schemas/GcpEntitlement'
      - $ref: '#/components/schemas/AzureEntitlement'
      - $ref: '#/components/schemas/RedHatEntitlement'
      type: object
    AzureCloud:
      type: string
      description: Azure Cloud
      default: azure
      enum:
      - azure
      example: azure
    SubscriptionContracted:
      allOf:
      - $ref: '#/components/schemas/Subscription'
      - $ref: '#/components/schemas/SubscriptionItem'
    ProductId:
      description: Cloud Marketplace issued ID for a product
      example: abcd-1234-efgh-5678
      anyOf:
      - $ref: '#/components/schemas/AwsProductId'
      - $ref: '#/components/schemas/GcpProductId'
      - $ref: '#/components/schemas/AzureProductId'
      - $ref: '#/components/schemas/RedHatProductId'
    AzureProductId:
      type: string
      description: Azure Offer ID
      example: tackle-azure-platform
      minLength: 0
    GcpProductId:
      type: string
      description: GCP Solution ID
      example: tackle-for-gcp
      minLength: 0
    RedHatSubscriptionType:
      type: string
      description: Type of the subscription
      enum:
      - TRIAL
      - FREE
      - PURCHASE
      example: TRIAL
    OfferId:
      type: string
      description: The AWS issued offer ID, Seller created Azure Plan ID, or the GCP issued Quote ID
    MarketplaceData:
      description: The marketplace data object contains fields specific to the marketplaces
      oneOf:
      - $ref: '#/components/schemas/AwsMarketplaceData'
      - $ref: '#/components/schemas/OtherMarketplaceData'
    RegistrationDetails:
      type: object
      minProperties: 3
      example:
        Company: Tackle
        Email Address: support@tackle.io
        Full Name: Jane Doe
        Company Website: https://tackle.io
        Phone Number: '1234567890'
      description: "Registration details of a purchaser that map to defined registration page fields for a given listing.\nThe following fields are required at a minimum:\n  - Company\n  - Email Address\n  - Full Name\nAdditional fields may be supplied, where the key matches the name of the custom registration field defined for a given listing.\nCustom registration fields may be defined on a per listing basis on the Settings page for a given listing via Tackle Platform UI:\n  https://downstream.tackle.io/listings/productid-goes-here/settings\n"
      properties:
        Company:
          type: string
          description: Company name of purchaser
          minLength: 0
        Email Address:
          type: string
          format: email
          description: Valid email address of purchaser
        Full Name:
          type: string
          description: Full name of purchaser
          minLength: 0
      required:
      - Company
      - Email Address
      - Full Name
    Entitlements:
      type: array
      description: A list of Entitlement objects
      uniqueItems: true
      minItems: 0
      example:
      - dimension: example_dimension_name
        expiration: '2019-04-24T12:23:03.048000+00:00'
        skuid: example_awsdimension_apiname_1
        value: 1
      - dimension: example_dimension_name2
        expiration: '2019-04-24T12:23:03.048000+00:00'
        value: 5
        skuid: example_awsdimension_apiname_1
      items:
        $ref: '#/components/schemas/Entitlement'
      readOnly: true
    GetSubscriptionResponse:
      title: GetSubscriptionResponse
      type: object
      description: Response describing data containing a single subscription and other metadata
      properties:
        data:
          $ref: '#/components/schemas/SubscriptionExpanded'
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
      - data
      - metadata
    RedHatEntitlement:
      type: object
      description: A purchase entitlement from Red Hat Marketplace
      properties:
        subscription_id:
          type: string
        edition_id:
          type: string
          description: Unique ID of the product's edition being subscribed to
        edition_name:
          type: string
          description: Readable name for the edition
        attributes:
          type: object
          description: Optional customer properties
        term:
          type: integer
          description: The duration of a single subscription term
        term_unit:
          $ref: '#/components/schemas/RedHatTermUnit'
        term_end_date:
          type: string
          description: The new term end date in format YYYY-MM-DD
          format: date
          example: '2021-11-02'
        type:
          $ref: '#/components/schemas/RedHatSubscriptionType'
        renew_type:
          $ref: '#/components/schemas/RedHatSubscriptionRenewType'
      required:
      - subscription_id
      - edition_id
      - edition_name
      - attributes
      - term
      - term_unit
      - term_end_date
      - type
      - renew_type
    GcpCloud:
      type: string
      description: GCP Cloud
      default: gcp
      enum:
      - gcp
      example: gcp
    SubscriptionExpanded:
      allOf:
      - $ref: '#/components/schemas/Subscription'
      - $ref: '#/components/schemas/SubscriptionDetails'
    Clouds:
      anyOf:
      - $ref: '#/components/schemas/AwsCloud'
      - $ref: '#/components/schemas/GcpCloud'
      - $ref: '#/components/schemas/AzureCloud'
      - $ref: '#/components/schemas/RedHatCloud'
      description: A string identifying a cloud marketplace
    RedHatProductId:
      type: string
      description: Red Hat Product Id
      example: d7a149a199100ad8a9931f14ea95cd00
      minLength: 0
  responses:
    401-Unauthorized-MTM:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            AuthorizationHeaderMissing:
              value:
                code: authorization_header_missing
                error: Authorization header is expected
                error_type: service_exception
                errors: []
            InvalidHeader:
              value:
                code: invalid_header
                error: Authorization header must start with Bearer
                error_type: service_exception
                errors: []
            InvalidToken:
              value:
                code: invalid_token
                error: Unable to validate authentication token. This token has no vendor associated with it.
                error_type: service_exception
                errors: []
            MissingExpiration:
              value:
                code: missing_expiration
                error: This token has an expired session.
                error_type: service_exception
                errors: []
            MtmTokenExpired:
              value:
                code: mtm_token_expired
                error: Token expired
                errors: []
    401-Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              value:
                code: unauthorized
                error: client_id and client_secret are invalid.
                error_type: service_exception
                errors: []
    Subscriptions_200-OK-Subscriptions:
      description: Example response for a list of subscriptions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListSubscriptionsResponse'
          examples:
            list-subscriptions-response:
              value:
                data:
                - tackle_subscription_id: 52fZSV7JbMI
                  productid: exampleproductid
                  product_link: https://api.tackle.io/v1/products/exampleproductid
                  cloud: aws
                  customerid: examplecustomerid
                  offerid: exampleofferid
                  created_at: '2021-11-09T12:00:00.000Z'
                  registered_at: '2021-11-10T12:00:00.000Z'
                  updated_at: '2021-11-11T12:00:00.000Z'
                  cancelled_at: '2021-11-11T12:00:00.000Z'
                  started_at: '2021-11-09T12:00:00.000Z'
                  ended_at: '2021-11-11T12:00:00.000Z'
                  link: https://api.tackle.io/v1/subscriptions/52fZSV7JbMI
                - tackle_subscription_id: v2RFsznlfb8
                  productid: exampleproductid
                  product_link: https://api.tackle.io/v1/products/exampleproductid
                  cloud: aws
                  customerid: examplecustomerid
                  offerid: exampleofferid2
                  created_at: '2021-11-12T12:00:00.000Z'
                  registered_at: '2021-11-13T12:00:00.000Z'
                  updated_at: '2021-11-13T12:00:00.000Z'
                  cancelled_at: null
                  started_at: '2021-11-12T12:00:00.000Z'
                  ended_at: '2022-11-12T12:00:00.000Z'
                  link: https://api.tackle.io/v1/subscriptions/v2RFsznlfb8
                metadata:
                  link: https://api.tackle.io/v1/subscriptions
    Subscriptions_200-OK-Subscription:
      description: Example response for a single subscription
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetSubscriptionResponse'
          examples:
            get-subscription-response:
              value:
                data:
                  tackle_subscription_id: 52fZSV7JbMI
                  productid: exampleproductid
                  product_link: https://api.tackle.io/v1/products/exampleproductid
                  cloud: gcp
                  customerid: examplecustomerid
                  offerid: exampleofferid2
                  created_at: '2021-11-12T12:00:00.000Z'
                  registered_at: '2021-11-13T12:00:00.000Z'
                  updated_at: '2021-11-13T12:00:00.000Z'
                  cancelled_at: null
                  started_at: '2021-11-12T12:00:00.000Z'
                  ended_at: '2022-11-12T12:00:00.000Z'
                  is_free_trial: false
                  registration_details:
                    Company: Tackle
                    Email Address: support@tackle.io
                    Full Name: Jane Doe
                    Company Website: https://tackle.io
                    Phone Number: '1234567890'
                  entitlements:
                  - dimension: example_entitlement_dimension1
                    expiration: '2022-11-12T12:00:00.000Z'
                    skuid: exampleproductid_awsdimension_1
                    value: 1
                  - dimension: example_entitlement_dimension2
                    expiration: '2022-11-12T12:00:00.000Z'
                    value: 10
                    skuid: exampleproductid_awsdimension_2
                metadata:
                  link: https://api.tackle.io/v1/subscriptions/52fZSV7JbMI
    Subscriptions_404-Not-Found-Subscription:
      description: Response if subscription was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            subscription-not-found:
              value:
                code: subscription_not_found
                error: Subscription was not found
                errors: []
  parameters:
    tackle_subscription_id:
      name: tackle_subscription_id
      description: Subscription ID generated by Tackle
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
    Start_date:
      name: start_date
      description: Start date for subscription query
      in: query
      required: false
      schema:
        type: string
        format: date-time
        example: '2021-11-29T16:10:15.000Z'
        pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d*)?Z$
    productid_query:
      name: productid
      description: Product ID for a query
      in: query
      schema:
        $ref: '#/components/schemas/ProductId'
    customerid:
      name: customerid
      description: Customer ID for a query
      in: query
      schema:
        $ref: '#/components/schemas/CustomerId'
    clouds:
      name: clouds
      description: Cloud for a query
      in: query
      schema:
        $ref: '#/components/schemas/Clouds'
    End_date:
      name: end_date
      description: End date for subscription query
      in: query
      required: false
      schema:
        type: string
        format: date-time
        example: '2021-11-29T16:10:01.000Z'
        pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d*)?Z$
  securitySchemes:
    BearerAuth:
      description: The Tackle API requires a JWT for authentication. You can get this by [getting your API credentials](https://developers.tackle.io/docs/how-to-get-an-m2m-client-id-and-secret) from the Tackle Platform then [retrieving your Access Token](https://developers.tackle.io/docs/getting-an-access-token) using our Authentication endpoint.
      type: http
      scheme: bearer
      bearerFormat: JWT
    BasicAuthCallback:
      description: Use `basic` for [basic HTTP authentication](https://en.wikipedia.org/wiki/Basic_access_authentication); this is only used for `callbacks`
      type: http
      scheme: basic
    HeaderApiKeyAuthCallback:
      description: Use `header_api_key` to specify a custom HTTP request header for authentication. Requests from Tackle will use the specified HTTP header for outbound requests to your Webhook URL; this is only used for `callbacks`'
      type: apiKey
      name: subscription-key
      in: header
    Oauth2AuthCallback:
      description: This auth-type is for `oauth2` client credentials flow. We will use the client_id and client_secret to call the token_url to get an access token; this is only used for `callbacks`'
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
externalDocs:
  description: Tackle Developer Hub and API Documentation
  url: https://developers.tackle.io
x-readme:
  explorer-enabled: false
  proxy-enabled: true
  samples-enabled: true