Talon.One Additional costs API

openapi: 3.2.0
info:
  title: Management Additional costs API
  version: ''
  description: 'The Management API allows you to programmatically do what the Campaign Manager

    does.'
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Additional costs
  description: 'Represents an extra fee applied to the cart, for example, shipping fees or processing fees.


    See the docs.'
paths:
  /v1/additional_costs:
    post:
      operationId: createAdditionalCost
      summary: Create additional cost
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Create an additional cost.


        These additional costs are shared across all applications in your account, and are never required.'
      tags:
      - Additional costs
      requestBody:
        $ref: '#/components/requestBodies/NewAdditionalCost'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAdditionalCost'
    get:
      operationId: getAdditionalCosts
      summary: List additional costs
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Returns all the defined additional costs for the account.'
      tags:
      - Additional costs
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - totalResultSize
                - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountAdditionalCost'
  /v1/additional_costs/{additionalCostId}:
    get:
      operationId: getAdditionalCost
      summary: Get additional cost
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Returns the additional cost.'
      tags:
      - Additional costs
      parameters:
      - name: additionalCostId
        description: 'The ID of the additional cost. You can find the ID the the Campaign Manager''s URL when you display the details of the cost in **Account** > **Tools** > **Additional costs**.

          '
        example: 2
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAdditionalCost'
    put:
      operationId: updateAdditionalCost
      summary: Update additional cost
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Updates an existing additional cost. Once created, the only property of an additional cost that cannot be changed is the `name` property (or **API name** in the Campaign Manager). This restriction is in place to prevent accidentally breaking live integrations.'
      tags:
      - Additional costs
      parameters:
      - name: additionalCostId
        description: 'The ID of the additional cost. You can find the ID the the Campaign Manager''s URL when you display the details of the cost in **Account** > **Tools** > **Additional costs**.

          '
        example: 2
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/NewAdditionalCost'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAdditionalCost'
components:
  parameters:
    sort:
      name: sort
      in: query
      required: false
      description: 'The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with `-`.


        **Note:** You may not be able to use all fields for sorting. This is due to performance limitations.

        '
      example: name
      schema:
        type: string
    skip:
      name: skip
      in: query
      required: false
      description: The number of items to skip when paging through large result sets.
      example: 100
      schema:
        type: integer
    pageSize:
      name: pageSize
      in: query
      required: false
      description: The number of items in the response.
      example: 1000
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 1000
  schemas:
    NewAdditionalCost:
      allOf:
      - type: object
        required:
        - name
        - title
        - description
        properties:
          name:
            type: string
            pattern: ^[A-Za-z]\w*$
            description: The internal name used in API requests.
            example: shippingFee
          title:
            type: string
            pattern: ^[A-Za-z][A-Za-z0-9_.!~*'() -]*$
            description: The human-readable name for the additional cost that will be shown in the Campaign Manager. Like `name`, the combination of entity and title must also be unique.
            example: Shipping fee
          description:
            type: string
            description: A description of this additional cost.
            example: A shipping fee
          subscribedApplicationsIds:
            type: array
            description: A list of the IDs of the applications that are subscribed to this additional cost.
            items:
              type: integer
            example:
            - 3
            - 13
          type:
            type: string
            enum:
            - session
            - item
            - both
            example: session
            description: 'The type of additional cost. Possible value:

              - `session`: Additional cost will be added per session.

              - `item`: Additional cost will be added per item.

              - `both`: Additional cost will be added per item and session.

              '
            default: session
    AccountEntity:
      type: object
      required:
      - accountId
      properties:
        accountId:
          type: integer
          description: The ID of the account that owns this entity.
          example: 3886
    AccountAdditionalCost:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/AccountEntity'
      - $ref: '#/components/schemas/NewAdditionalCost'
    Entity:
      type: object
      required:
      - id
      - created
      properties:
        id:
          type: integer
          description: The internal ID of this entity.
          example: 6
        created:
          type: string
          format: date-time
          description: The time this entity was created.
          example: '2020-06-10T09:05:27.993483Z'
  requestBodies:
    NewAdditionalCost:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewAdditionalCost'
      description: body
      required: true
  securitySchemes:
    manager_auth:
      type: apiKey
      name: Authorization
      in: header
      description: 'This authentication scheme relies on a bearer token that you can use to

        access all the endpoints of the Management API.


        To create the token:


        1. Get a bearer token by calling the

        [createSession](#tag/Sessions/operation/createSession) endpoint.

        1. Use the `token` property of the response in the HTTP header of your

        next queries: `Authorization: Bearer $TOKEN`.


        A token is valid for 3 months. In accordance with best pratices, use

        your generated token for all your API requests. Do **not** regenerate a token for each

        request.


        > [!note]

        > We recommend that you use a [Management API key](https://docs.talon.one/management-api#section/Authentication/management_key)

        > instead of a bearer token.

        '
    management_key:
      type: apiKey
      name: Authorization
      in: header
      description: "The API key authentication gives you access to the endpoints selected by\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n   **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n"