Talon.One Store budgets API

openapi: 3.2.0
info:
  title: Management Store budgets 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: Store budgets
  description: Represents store budgets. You can set a store budget to limit the total amount an individual store can spend in a campaign.
paths:
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/budgets:
    post:
      operationId: createCampaignStoreBudget
      summary: Create campaign store budget
      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 a new store budget for a given campaign.'
      tags:
      - Store budgets
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCampaignStoreBudget'
        description: body
        required: true
      responses:
        '201':
          description: Created
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: listCampaignStoreBudgetLimits
      summary: List campaign store budget limits
      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.


        Return the store budget limits for a given campaign.'
      tags:
      - Store budgets
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: action
        in: query
        description: The action that this budget is limiting.
        example: setDiscount
        required: false
        schema:
          type: string
          enum:
          - setDiscount
      - name: period
        in: query
        description: 'The period to which the limit applies.


          **Note**: For budgets with no period, set this to `overall`.

          '
        example: weekly
        required: false
        schema:
          type: string
          enum:
          - overall
          - daily
          - weekly
          - monthly
          - yearly
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ListCampaignStoreBudgets'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteCampaignStoreBudgets
      summary: Delete campaign store budgets
      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.


        Delete the store budgets for a given campaign.'
      tags:
      - Store budgets
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: action
        in: query
        description: The action that this budget is limiting.
        example: setDiscount
        required: false
        schema:
          type: string
          enum:
          - setDiscount
      - name: period
        in: query
        description: 'The period to which the limit applies.


          **Note**: For budgets with no period, set this to `overall`.

          '
        example: weekly
        required: false
        schema:
          type: string
          enum:
          - overall
          - daily
          - weekly
          - monthly
          - yearly
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/budgets/summary:
    get:
      operationId: summarizeCampaignStoreBudget
      summary: Get summary of campaign store budgets
      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.


        Fetch a summary of all store budget information for a given campaign.'
      tags:
      - Store budgets
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SummaryCampaignStoreBudget'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/budgets/import:
    post:
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                upFile:
                  description: The CSV file containing the data that is being imported.
                  type: string
                  format: binary
      operationId: importCampaignStoreBudget
      summary: Import campaign store budgets
      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.


        Upload a CSV file containing store budgets for a given campaign.


        Send the file as multipart data.


        The CSV file **must** only contain the following columns:

        - `store_integration_id`: The identifier of the store.

        - `limit`: The budget limit for the store.


        The import **replaces** the previous list of store budgets.'
      tags:
      - Store budgets
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: action
        in: query
        description: The action that this budget is limiting.
        example: setDiscount
        required: false
        schema:
          type: string
          enum:
          - setDiscount
      - name: period
        in: query
        description: 'The period to which the limit applies.


          **Note**: For budgets with no period, set this to `overall`.

          '
        example: weekly
        required: false
        schema:
          type: string
          enum:
          - overall
          - daily
          - weekly
          - monthly
          - yearly
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/budgets/export:
    get:
      operationId: exportCampaignStoreBudgets
      summary: Export campaign store budgets
      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.


        Download a CSV file containing the store budgets for a given campaign.


        > [!tip] If the exported CSV file is too large to view, you can

        > split it into multiple files.


        The CSV file contains the following columns:


        - `store_integration_id`: The identifier of the store.

        - `limit`: The budget limit for the store.'
      tags:
      - Store budgets
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: action
        in: query
        description: The action that this budget is limiting.
        example: setDiscount
        required: false
        schema:
          type: string
          enum:
          - setDiscount
      - name: period
        in: query
        description: 'The period to which the limit applies.


          **Note**: For budgets with no period, set this to `overall`.

          '
        example: weekly
        required: false
        schema:
          type: string
          enum:
          - overall
          - daily
          - weekly
          - monthly
          - yearly
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: 'store_integration_id,limit

                    STORE-001,10

                    STORE-002,20

                    STORE-003,30

                    '
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    NewCampaignStoreBudgetStoreLimit:
      type: object
      required:
      - storeId
      - limit
      properties:
        storeId:
          type: integer
          description: 'The ID of the store.

            You can get this ID with the [List stores](#tag/Stores/operation/listStores) endpoint.

            '
          example: 17
        limit:
          type: number
          example: 1000
          description: The value to set for the limit.
    SummaryCampaignStoreBudget:
      type: object
      required:
      - action
      - storeCount
      - imported
      properties:
        action:
          type: string
          enum:
          - redeemCoupon
          - redeemReferral
          - setDiscount
          - setDiscountEffect
          - createCoupon
          - createReferral
          - createLoyaltyPoints
          - redeemLoyaltyPoints
          - customEffect
          - createLoyaltyPointsEffect
          - redeemLoyaltyPointsEffect
          - callApi
          - awardGiveaway
          - addFreeItemEffect
          - reserveCoupon
        period:
          type: string
          enum:
          - overall
          - daily
          - weekly
          - monthly
          - yearly
        storeCount:
          type: integer
        imported:
          type: boolean
    ListCampaignStoreBudgets:
      type: object
      required:
      - store
      - limit
      - action
      properties:
        store:
          $ref: '#/components/schemas/ListCampaignStoreBudgetsStore'
          type: object
        limit:
          type: integer
        action:
          type: string
        period:
          type: string
    NewCampaignStoreBudget:
      type: object
      required:
      - action
      - storeLimits
      properties:
        action:
          type: string
          enum:
          - setDiscount
        storeLimits:
          type: array
          description: The set of budget limits for stores linked to the campaign.
          items:
            $ref: '#/components/schemas/NewCampaignStoreBudgetStoreLimit'
        period:
          type: string
          enum:
          - daily
          - weekly
          - monthly
          - yearly
    UserEntity:
      type: object
      required:
      - userId
      properties:
        userId:
          type: integer
          description: The ID of the user associated with this entity.
          example: 388
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A message describing the error.
        errors:
          type: array
          description: An array of individual problems encountered during the request.
          items:
            $ref: '#/components/schemas/APIError'
    APIError:
      type: object
      required:
      - source
      - title
      properties:
        title:
          type: string
          description: Short description of the problem.
        details:
          type: string
          description: Longer description of this specific instance of the problem.
        source:
          $ref: '#/components/schemas/ErrorSource'
    Import:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/AccountEntity'
      - $ref: '#/components/schemas/UserEntity'
      - type: object
        required:
        - amount
        - entity
        properties:
          entity:
            type: string
            example: AttributeAllowedList
            description: 'The name of the entity that was imported.

              '
          amount:
            type: integer
            minimum: 0
            example: 10
            description: The number of values that were imported.
    AccountEntity:
      type: object
      required:
      - accountId
      properties:
        accountId:
          type: integer
          description: The ID of the account that owns this entity.
          example: 3886
    ListCampaignStoreBudgetsStore:
      type: object
      required:
      - id
      - integrationId
      - name
      properties:
        id:
          type: integer
        integrationId:
          type: string
        name:
          type: string
    ErrorSource:
      type: object
      description: 'The source of the current error, exactly one of `pointer`, `parameter` or `line` will be defined.

        '
      properties:
        pointer:
          type: string
          description: Pointer to the path in the payload that caused this error.
        parameter:
          type: string
          description: Query parameter that caused this error.
        line:
          type: string
          description: Line number in uploaded multipart file that caused this error. 'N/A' if unknown.
        resource:
          type: string
          description: Pointer to the resource that caused this error.
    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'
  parameters:
    campaignId:
      name: campaignId
      in: path
      description: The ID of the campaign. It is displayed in your Talon.One deployment URL.
      example: 18
      required: true
      schema:
        type: integer
    applicationId:
      name: applicationId
      in: path
      required: true
      description: The ID of the Application. It is displayed in your Talon.One deployment URL.
      example: 42
      schema:
        type: integer
  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"