Tackle Private Offer Actions API

openapi: 3.0.3
info:
  title: Tackle Authentication Private Offer Actions 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: Private Offer Actions
  description: Private offer lifecycle actions such as archive, cancel, and sync.
paths:
  /api/private-offers/{id}/archive:
    post:
      tags:
      - Private Offer Actions
      summary: Archive an offer
      description: 'Marks an offer as archived and records an archive activity without

        changing the offer state or status.


        Required RBAC action: `offers:UpdateOffer`.

        '
      operationId: archivePrivateOffer
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OfferId'
      - $ref: '#/components/parameters/TackleOperationId'
      responses:
        '200':
          description: Offer archived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateOffer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/private-offers/{id}/unarchive:
    post:
      tags:
      - Private Offer Actions
      summary: Unarchive an offer
      description: 'Clears an offer''s archived flag and records an unarchive activity without

        changing the offer state or status.


        Required RBAC action: `offers:UpdateOffer`.

        '
      operationId: unarchivePrivateOffer
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OfferId'
      - $ref: '#/components/parameters/TackleOperationId'
      responses:
        '200':
          description: Offer unarchived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateOffer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/private-offers/{id}/cancel:
    post:
      tags:
      - Private Offer Actions
      summary: Cancel an offer
      description: 'Cancels an offer. Accepted offers cannot be canceled. Offers that have

        already been created in Microsoft are moved to pending cancellation,

        while offers that have not reached Microsoft are marked canceled.


        Required RBAC action: `offers:UpdateOffer`.

        '
      operationId: cancelPrivateOffer
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OfferId'
      - $ref: '#/components/parameters/TackleOperationId'
      responses:
        '200':
          description: Offer canceled or cancellation requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateOffer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/private-offers/{id}/sync:
    post:
      tags:
      - Private Offer Actions
      summary: Sync an offer from Microsoft
      description: 'Synchronizes the stored Tackle offer from Microsoft. The offer must

        already be associated to a Microsoft offer reference.


        Required RBAC action: `offers:GetOffer`.

        '
      operationId: syncPrivateOffer
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OfferId'
      - $ref: '#/components/parameters/UpdateDocs'
      - $ref: '#/components/parameters/TackleOperationId'
      responses:
        '200':
          description: Offer synchronized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateOffer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    UpdateDocs:
      name: update_docs
      in: query
      required: false
      description: Whether the manual sync should refresh associated documents.
      schema:
        type: boolean
        default: false
      example: true
    OfferId:
      name: id
      in: path
      required: true
      description: Tackle private offer ID.
      schema:
        type: string
      example: po-1234
    TackleOperationId:
      name: tackle-operation-id
      in: header
      required: false
      description: Optional caller-provided operation ID for request tracing.
      schema:
        type: string
      example: 018f01ec-3f2b-7a70-b81e-4fc3d6a69f42
  schemas:
    MsftResponse:
      type: object
      properties:
        job_id:
          type: string
        offer_id:
          type:
          - string
          - 'null'
        resource_uri:
          type:
          - string
          - 'null'
        raw_response:
          type: string
    PrivateOfferError:
      type: object
      properties:
        source:
          type: string
        type:
          type: string
        message:
          type: string
    Partner:
      type: object
      properties:
        partner_name:
          type:
          - string
          - 'null'
        partner_seller_id:
          type: string
    InitialCharge:
      type: object
      properties:
        price_per_payment_in_usd:
          type:
          - number
          - 'null'
          format: double
        note:
          type:
          - string
          - 'null'
    PrivateOfferState:
      type: object
      properties:
        draft:
          oneOf:
          - $ref: '#/components/schemas/PrivateOfferStateDetail'
          - type: 'null'
        submitted:
          oneOf:
          - $ref: '#/components/schemas/PrivateOfferStateDetail'
          - type: 'null'
        accepted:
          oneOf:
          - $ref: '#/components/schemas/PrivateOfferStateDetail'
          - type: 'null'
        current_cloud:
          oneOf:
          - $ref: '#/components/schemas/PrivateOfferStateDetail'
          - type: 'null'
        last_modified:
          type: string
          format: date-time
    ProductType:
      type: string
      enum:
      - saas
      - ami
      - professional_services
    PaymentInstallment:
      type: object
      properties:
        price_per_payment_in_usd:
          type: number
          format: double
    ContractDuration:
      type: object
      properties:
        type:
          type: string
          example: month
        frequency:
          type: integer
          example: 12
    UserLimits:
      type: object
      properties:
        min:
          type: integer
        max:
          type: integer
    PrivateOffer:
      type: object
      description: Stored Tackle Microsoft private offer.
      properties:
        po_id:
          type: string
        accepted_at:
          type:
          - string
          - 'null'
          format: date-time
        accepted_source:
          type:
          - string
          - 'null'
        archived_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        cancelled_at:
          type:
          - string
          - 'null'
          format: date-time
        last_modified_at:
          type: string
          format: date-time
        last_update_source:
          type:
          - string
          - 'null'
        viewed_offer_at:
          type:
          - string
          - 'null'
          format: date-time
        sent_at:
          type:
          - string
          - 'null'
          format: date-time
        submitted_at:
          type:
          - string
          - 'null'
          format: date-time
        opened_instructions_at:
          type:
          - string
          - 'null'
          format: date-time
        subscribed_at:
          type:
          - string
          - 'null'
          format: date-time
        partner_marked_up_at:
          type:
          - string
          - 'null'
          format: date-time
        marketplace_acceptance_link:
          type:
          - string
          - 'null'
          format: uri
        salesforce:
          $ref: '#/components/schemas/PrivateOfferSalesforce'
        vendor_id:
          type: string
        vendor_name:
          type: string
        product_contact_email:
          type: string
          format: email
        state:
          $ref: '#/components/schemas/OfferStateValue'
        status:
          $ref: '#/components/schemas/OfferStatus'
        offer_type:
          $ref: '#/components/schemas/OfferType'
        marketplace_fee:
          type: number
          format: double
        activities:
          type: array
          items:
            $ref: '#/components/schemas/PrivateOfferActivity'
        archived:
          type: boolean
        version:
          type: string
        product_id:
          type: string
        product_name:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        marketplace_created_at:
          type:
          - string
          - 'null'
          format: date-time
        clone:
          oneOf:
          - $ref: '#/components/schemas/Clone'
          - type: 'null'
        metadata:
          type: object
          additionalProperties:
            type: string
        product_type:
          $ref: '#/components/schemas/ProductType'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/PrivateOfferError'
        pre_registration_details:
          $ref: '#/components/schemas/PreRegistrationDetails'
        ui_state:
          $ref: '#/components/schemas/OfferStateValue'
        partner:
          oneOf:
          - $ref: '#/components/schemas/Partner'
          - type: 'null'
        total_contract_value_gross_amount:
          type: number
          format: double
        total_contract_value_net_amount:
          type: number
          format: double
        est_min_total_contract_value_gross_amount:
          type: number
          format: double
        est_min_total_contract_value_net_amount:
          type: number
          format: double
        est_max_total_contract_value_gross_amount:
          type: number
          format: double
        est_max_total_contract_value_net_amount:
          type: number
          format: double
        name:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        buyer_details:
          $ref: '#/components/schemas/BuyerDetails'
        renewal:
          type: boolean
        eula:
          $ref: '#/components/schemas/EULA'
        product_ref:
          type: string
        users_to_notify:
          type: array
          items:
            $ref: '#/components/schemas/UserToNotify'
        pricing:
          $ref: '#/components/schemas/OfferPricing'
        preparer_email:
          type: string
          format: email
        start_on:
          $ref: '#/components/schemas/StartOn'
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        accept_by_date:
          type: string
          format: date
        offer_ref:
          type:
          - string
          - 'null'
        plan_template:
          $ref: '#/components/schemas/PlanTemplate'
        plan_ref:
          type:
          - string
          - 'null'
        subscription_ref:
          type:
          - string
          - 'null'
        notes:
          type:
          - string
          - 'null'
        offer_state:
          $ref: '#/components/schemas/PrivateOfferState'
        msft_response:
          $ref: '#/components/schemas/MsftResponse'
    StartOn:
      type: string
      enum:
      - acceptance
      - custom
    PrivateOfferActivityUser:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        principal_type:
          type: string
    Buyer:
      type: object
      properties:
        full_name:
          type: string
        email_address:
          type: string
          format: email
        title:
          type: string
    PaymentModel:
      type: string
      enum:
      - PaymentSchedule
      - PerYear
      - OneTime
      - PerMonth
    ScheduleDetail:
      type: object
      properties:
        charge_date:
          type:
          - string
          - 'null'
          format: date
        price_per_payment_in_usd:
          type:
          - number
          - 'null'
          format: double
        note:
          type:
          - string
          - 'null'
    PrivateOfferStateDetail:
      type: object
      properties:
        raw_message:
          type: string
    Dimension:
      type: object
      properties:
        enabled:
          type: boolean
        id:
          type: string
        unit_of_measure:
          type: string
        price_per_unit_in_usd:
          type: number
          format: double
        included_quantities:
          type: array
          items:
            $ref: '#/components/schemas/DimensionQuantity'
    DimensionQuantity:
      type: object
      properties:
        dimension_term:
          $ref: '#/components/schemas/ContractDuration'
        unlimited_quantity:
          type: boolean
        quantity:
          type: number
          format: double
    OfferStatus:
      type: string
      description: 'Controls the offer workflow. Use `draft_status` to save the offer in

        Tackle only. Use `submit_to_cloud` to validate the offer and prepare it

        for Microsoft marketplace submission.

        '
      enum:
      - draft_status
      - draft_in_marketplace_status
      - submit_to_cloud
      - created_in_cloud
      - sent_to_cloud
      - pending_cancellation
      - partner_marked_up
      - canceled
      - accepted
      - withdrawn_canceled
      - errored
      - subscribed
      - expired
      - job_status_pending
      - detail_retrieval_pending
      - withdraw_pending
      - delete_pending
      - delete_validation_pending
      - deleted
    Source:
      type: string
      enum:
      - salesforce
      - tackle
      - microsoft
    PlanTemplate:
      type: object
      properties:
        ref:
          type: string
        display:
          type: string
    BuyerDetails:
      type: object
      properties:
        company_name:
          type: string
        billing_account_id:
          type: string
        buyers:
          type: array
          items:
            $ref: '#/components/schemas/Buyer'
    OfferType:
      type: string
      enum:
      - direct
      - partner
    PrivateOfferActivity:
      type: object
      properties:
        slug:
          type:
          - string
          - 'null'
          example: created-draft-offer
        user_id:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        metadata:
          type:
          - object
          - 'null'
          additionalProperties: true
        user:
          oneOf:
          - $ref: '#/components/schemas/PrivateOfferActivityUser'
          - type: 'null'
    PricingType:
      type: string
      enum:
      - flat_rate
      - per_user
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: missing id
    EULA:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: Offer EULA type.
          example: standard
        document_urns:
          type: array
          items:
            type: string
        merged_urn:
          type:
          - string
          - 'null'
        presigned_url:
          type:
          - string
          - 'null'
          format: uri
    PaymentSchedule:
      type: object
      properties:
        initial_charge:
          $ref: '#/components/schemas/InitialCharge'
        payment_schedule:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleDetail'
    OfferPricing:
      type: object
      properties:
        plan_ref:
          type: string
          description: Microsoft plan ID.
        plan_name:
          type: string
        description:
          type: string
        contract_duration:
          $ref: '#/components/schemas/ContractDuration'
        payment_model:
          $ref: '#/components/schemas/PaymentModel'
        payment_installments:
          oneOf:
          - $ref: '#/components/schemas/PaymentInstallment'
          - type: 'null'
        payment_schedule:
          oneOf:
          - $ref: '#/components/schemas/PaymentSchedule'
          - type: 'null'
        pricing_type:
          oneOf:
          - $ref: '#/components/schemas/PricingType'
          - type: 'null'
        user_limits:
          oneOf:
          - $ref: '#/components/schemas/UserLimits'
          - type: 'null'
        dimensions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Dimension'
    Clone:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/Source'
        originating_offer_id:
          type: string
    UserToNotify:
      type: object
      properties:
        contact_type:
          type: string
        value:
          type:
          - string
          - 'null'
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
    OfferStateValue:
      type: string
      enum:
      - draft
      - pending
      - submitted_in_cloud
      - created_in_cloud
      - email_sent
      - instructions_opened
      - viewed
      - partner_marked_up
      - accepted
      - subscribed
      - attention_needed
      - pending_cancellation
      - pending_cancellation_withdrawn
      - canceled
      - deleted_in_cloud
    PreRegistrationDetails:
      type: object
      properties:
        company_website:
          type:
          - string
          - 'null'
          format: uri
        details:
          type: object
          additionalProperties:
            type: string
    PrivateOfferSalesforce:
      type: object
      properties:
        created_at:
          type:
          - string
          - 'null'
          format: date-time
        custom_object_id:
          type:
          - string
          - 'null'
        opportunity_id:
          type:
          - string
          - 'null'
  responses:
    NotFoundError:
      description: Requested offer or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: not found
    BadRequestError:
      description: Invalid request or unsupported operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: missing id
    ForbiddenError:
      description: Caller is not allowed to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: forbidden
    InternalServerError:
      description: Internal server error or upstream dependency failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnauthorizedError:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: unauthorized
  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