Tackle.io Registrations API

openapi: 3.0.3
info:
  title: Tackle Public Contracts Authentication Registrations API
  description: "Customer-facing read API for cloud marketplace contracts that Tackle has\ningested for your Tackle account.\n\nThe response shape is a stable projection of the underlying\ncontract document. It is intended to be safe to consume long-term: fields\nwill be added over time, but documented fields will not be removed without\ndeprecation notice.\n\n## Authentication\n\nEvery request must include a valid Tackle JWT in the `Authorization`\nheader (`Authorization: Bearer <token>`). Machine-to-machine (MTM) tokens\nissued for your Tackle account are accepted. The token scopes every\nresponse to the account it represents.\n\n## Pagination\n\n`GET /api/contracts` is the only paginated endpoint. Pagination uses an\nopaque `cursor` query parameter:\n\n1. The first request omits `cursor`.\n2. If more pages exist, the response includes a `next` field. Pass that\n   value verbatim back as `cursor` on the next request.\n3. The last page omits `next`.\n\nCursors are opaque tokens. Do not parse, modify, or persist them across\nschema changes — request a fresh page from the start instead.\n"
  version: 1.0.0
servers:
- url: https://contracts.tackle.io
  description: Production
security:
- tackleJwt: []
tags:
- name: Registrations
  description: Operations for Order Registrations
paths:
  /v1/registrations:
    parameters: []
    post:
      tags:
      - Registrations
      summary: Register an Order
      description: Notify Tackle of order modifications or registrations (like when a submission is made on your self-hosted registration page)
      operationId: v1-create-registration
      responses:
        '200':
          $ref: '#/components/responses/Registrations_200-OK-Registration-Successful'
        '400':
          $ref: '#/components/responses/Registrations_400-Bad-Request'
        '401':
          $ref: '#/components/responses/401-Unauthorized-MTM'
        '403':
          $ref: '#/components/responses/Registrations_403-Forbidden'
        '404':
          $ref: '#/components/responses/Registrations_404-Not-Found'
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationsRequest'
            examples:
              RegistrationWithMinimumFields:
                summary: Minimum required registration details
                value:
                  productid: exampleproductid
                  customerid: examplecustomerid
                  details:
                    Company: Tackle
                    Email Address: support@tackle.io
                    Full Name: Jane Doe
              RegistrationWithAdditionalCustomFields:
                summary: Minimum + additional custom registration details
                value:
                  productid: exampleproductid
                  customerid: examplecustomerid
                  details:
                    Company: Tackle
                    Email Address: support@tackle.io
                    Full Name: Jane Doe
                    Company Website: https://tackle.io
                    Phone Number: '1234567890'
        description: Specifies the productid and customerid and registration details for a given order registration
      security:
      - BearerAuth: []
components:
  schemas:
    AwsProductId:
      type: string
      description: AWS Product Code
      example: 1test1a2b3c4d5e6f7g8h9ijk
      minLength: 0
    AzureCustomerId:
      type: string
      description: Azure Subscription ID
      example: 1b3gs3f4-2794-abcd-3fa3-063ga0s3t3re
      minLength: 0
    RegistrationsRequest:
      title: RegistrationsRequest
      type: object
      properties:
        productid:
          $ref: '#/components/schemas/ProductId'
        customerid:
          $ref: '#/components/schemas/CustomerId'
        details:
          $ref: '#/components/schemas/RegistrationDetails'
      required:
      - productid
      - customerid
      - details
      example:
        productid: exampleproductid
        customerid: examplecustomerid
        details:
          Company: Tackle
          Email Address: support@tackle.io
          Full Name: Jane Doe
          Company Website: https://tackle.io
          Phone Number: '1234567890'
    AzureProductId:
      type: string
      description: Azure Offer ID
      example: tackle-azure-platform
      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
    RedHatProductId:
      type: string
      description: Red Hat Product Id
      example: d7a149a199100ad8a9931f14ea95cd00
      minLength: 0
    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
    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
    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
    GcpCustomerId:
      type: string
      description: GCP External Account ID
      example: E-ABC2-D330-E2FG-H2Q2
      minLength: 0
    RedHatCustomerId:
      type: string
      description: Red Hat Customer Id
      example: 615334398743ac63d55cc4db
      minLength: 0
    RedHatSubscriptionRenewType:
      type: string
      description: Renew Type
      enum:
      - ORIGINAL_TERM
      - TERMINATE
      example: ORIGINAL_TERM
    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'
    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
    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 '
    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
    RedHatSubscriptionType:
      type: string
      description: Type of the subscription
      enum:
      - TRIAL
      - FREE
      - PURCHASE
      example: TRIAL
    AwsCustomerId:
      type: string
      description: AWS Account Reference ID
      example: ij3sXMkN3or
      minLength: 0
    RegistrationsResponse:
      title: RegistrationResponse
      type: object
      properties:
        entitlements:
          $ref: '#/components/schemas/Entitlements'
      required:
      - entitlements
    RedHatTermUnit:
      type: string
      description: The unit for the term
      enum:
      - DAYS
      - WEEKS
      - MONTHS
      - YEARS
      example: MONTHS
    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
    GcpProductId:
      type: string
      description: GCP Solution ID
      example: tackle-for-gcp
      minLength: 0
    CustomerId:
      anyOf:
      - $ref: '#/components/schemas/AwsCustomerId'
      - $ref: '#/components/schemas/GcpCustomerId'
      - $ref: '#/components/schemas/AzureCustomerId'
      - $ref: '#/components/schemas/RedHatCustomerId'
  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: []
    Registrations_403-Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ActivationFailureAzure:
              value:
                code: activation_failure
                error: 'Azure activation failure: 403'
                error_type: service_exception
                errors: []
            AccountApprovalFailureGcp:
              value:
                code: account_approval_failure
                error: Failed to approve GCP account
                error_type: service_exception
                errors: []
            EntitlementApprovalFailureGcp:
              value:
                code: entitlement_approval_failure
                error: Failed to approve GCP entitlement
                error_type: service_exception
                errors: []
            InvalidConfigurationAzure:
              value:
                code: invalid_configuration
                error: Vendor 'DEMOVENDOR1' has no azure configuration
                error_type: service_exception
                errors: []
            InvalidEntitlementsAws:
              value:
                code: invalid_entitlements
                error: Entitlements failed to be fetched from AWS. This can be caused by attempting a purchase with a non-payer AWS account.
                error_type: service_exception
                errors: []
            MissingEntitlementsAws:
              value:
                code: missing_entitlements
                error: Entitlements are missing from AWS. This can be caused by attempting a purchase with a rejected payment method.
                error_type: service_exception
                errors: []
            MissingEntitleMentsGcp:
              value:
                code: invalid_entitlements
                error: Entitlements failed to be fetched from AWS. This can be caused by attempting a purchase with a non-payer AWS account.
                error_type: service_exception
                errors: []
            NoAccountGcp:
              value:
                code: no_account
                error: Unable to find GCP account for order DEMOPRODUCT
                error_type: service_exception
                errors: []
            ProcurementServiceErrorGcp:
              value:
                code: procurement_service_error
                error: 'Procurement service error: GCP Configuration not found for vendor DEMOVENDOR1'
                error_type: service_exception
                errors: []
    Registrations_404-Not-Found:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            VendorNotFound:
              $ref: '#/components/examples/VendorNotFound'
            ProductNotFound:
              $ref: '#/components/examples/ProductNotFound'
            OrdertNotFound:
              $ref: '#/components/examples/OrderNotFound'
    Registrations_200-OK-Registration-Successful:
      description: Example success response after creating or updating a registration.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegistrationsResponse'
          examples:
            registration-aws:
              $ref: '#/components/examples/AwsEntitlements'
            registration-gcp:
              $ref: '#/components/examples/GcpEntitlements'
            registration-azure:
              $ref: '#/components/examples/AzureEntitlements'
            registration-redhat:
              $ref: '#/components/examples/RedHatEntitlements'
    Registrations_400-Bad-Request:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            InvalidDetails:
              value:
                code: invalid_details
                error: 'Invalid registration details {''Company'': ''Demo Company'', ''Email Address'': ''demo@example.com''} for product A0BCD23E.'
                error_type: service_exception
                errors:
                - 'Missing fields: Company Website (Website), Company Address, Phone Number'
                - 'Invalid fields: Additional Note'
            InvalidProduct:
              value:
                code: invalid_product
                error: The product 'A0BCD23E' is not configured for self hosted registration. A registration redirect must be defined.
                error_type: service_exception
                errors: []
            InvalidPayloadFormat:
              $ref: '#/components/examples/InvalidPayloadFormat'
            InvalidFields:
              $ref: '#/components/examples/InvalidFields'
  examples:
    OrderNotFound:
      summary: Example of order not found
      value:
        code: order_not_found
        error: An order was not found for vendor 'DEMOVENDOR1' and customer 'WXYZABCDEFG'.
        error_type: service_exception
        errors: []
    RedHatEntitlements:
      summary: Example of Red Hat entitlements list
      value:
        entitlements:
        - subscription_id: 5f3acdeae27a6b538020d09a
          edition_id: EIDJWBWL
          edition_name: Test Edition 1
          attributes:
            part1: 10
            sku1: 50
            part2: PREMIUM
            sku2: 50
          term: 12
          term_unit: MONTHS
          term_end_date: '2021-11-03'
          type: PURCHASE
          renew_type: ORIGINAL_TERM
    AwsEntitlements:
      summary: Example of AWS entitlements list
      value:
        entitlements:
        - 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
    VendorNotFound:
      summary: Example of vendor not found
      value:
        code: vendor_not_found
        error: The vendor 'DEMOVENDOR1' was not found.
        error_type: service_exception
        errors: []
    AzureEntitlements:
      summary: Example of Azure entitlements list
      value:
        entitlements:
        - plan: tackleazureplatform_azurelisting
          quantity: 5
          subscription_id: 1b3gs3f4-2794-abcd-3fa3-062fa0s3t3re
          subscription_name: Tackle Azure Platform
          offer_id: tackle-azure-platform
    GcpEntitlements:
      summary: Example of GCP entitlements list
      value:
        entitlements:
        - name: providers/tackle-public/entitlements/416bacaa-94b6-4701-911bf945aab9
          account: providers/tackle-public/accounts/E-ABC2-D530-E2FG-H2Q2
          createTime: '2019-10-25T21:38:20.865Z'
          updateTime: '2019-10-25T21:38:20.865Z'
          provider: tackle-public
          product: tackle-on-gcp
          plan: mp1-platform-3-P1Y
          state: ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL
          newPendingPlan: mp1-starter-P1Y
          quoteExternalName: mp1_sass
          productExternalName: mp1-marketplace
    ProductNotFound:
      summary: Example of product not found
      value:
        code: product_not_found
        error: Product 'A0BCD23E' was not found for vendor 'DEMOVENDOR1'.
        error_type: service_exception
        errors: []
    InvalidPayloadFormat:
      summary: Example of invalid payload format
      value:
        code: invalid_payload_format
        error: Payload must be valid JSON and UTF-8 encoded
        error_type: service_exception
        errors: []
    InvalidFields:
      summary: Example of invalid fields
      value:
        code: invalid_fields
        error: Validation Error
        errors:
        - loc:
          - customerid
          msg: field required
          type: value_error.missing
  securitySchemes:
    tackleJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Tackle-issued JWT (interactive user or MTM token).