MOLOCO Spend Cap API

openapi: 3.2.0
info:
  title: Management Spend Cap API
  description: MOLOCO RMP Management API provides functionalities for MOLOCO RMP systems.
  version: '1.0'
  contact:
    name: Moloco Inc.
    url: https://www.molocoads.com
servers:
- url: https://<platform>-mgmt.mcm-api.moloco.com
security:
- ApiKeyAuth: []
tags:
- name: SpendCap
paths:
  /rmp/mgmt/v1/platforms/{platform_id}/ad-accounts/{ad_account_id}/spend-caps:
    get:
      summary: ListSpendCaps
      description: List spend caps for an ad account.
      operationId: RmpManagementApi_ListSpendCaps
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicListSpendCapsResponse'
        '400':
          description: Bad request. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '404':
          description: Not found. One or more required resources do not exist.You can see the details in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '500':
          description: Internal server error. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
      parameters:
      - name: platform_id
        description: Identifier of the platform. Passed as a path parameter.
        in: path
        required: true
        schema:
          type: string
      - name: ad_account_id
        description: AdAccount id.
        in: path
        required: true
        schema:
          type: string
      - name: filter.status
        description: "Filter by spend cap status.\n\n - SCHEDULED: The SpendCap is not in an Active state due to an unexpected error case\n Similar to the Scheduled state of a campaign, the SpendCap is in a “reserved” state because its period has not yet started.\n - INACTIVE: The status when the user manually changes the SpendCap from Active to Inactive.\n - ACTIVE: The SpendCap is in an Active state. As long as the amount is not depleted, the mapped campaigns can remain Active and serve ads without issues\n - ENDED: One of the cases where the SpendCap is no longer Active because its defined period has ended.\n - DEPLETED: The SpendCap has reached its allocated amount (0 remaining). As a result, the mapped campaigns can no longer remain active and ad serving stops, even though the period itself has not yet ended.\n - ERROR: Error state. The campaign state does not belong to any states above."
        in: query
        required: false
        schema:
          type: string
          enum:
          - UNKNOWN_SPEND_CAP_STATUS
          - SCHEDULED
          - INACTIVE
          - ACTIVE
          - ENDED
          - DEPLETED
          - ERROR
          default: UNKNOWN_SPEND_CAP_STATUS
      tags:
      - SpendCap
    post:
      summary: CreateSpendCap
      description: Create a spend cap of an ad account.
      operationId: RmpManagementApi_CreateSpendCap
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicCreateSpendCapResponse'
        '400':
          description: Bad request. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '404':
          description: Not found. One or more required resources do not exist.You can see the details in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '500':
          description: Internal server error. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
      parameters:
      - name: platform_id
        description: Identifier of the platform who requests management api. It is passed as a path parameter.
        in: path
        required: true
        schema:
          type: string
      - name: ad_account_id
        description: AdAccount id.
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Title of spend cap. Required.
                schedule:
                  $ref: '#/components/schemas/rmpcommonTimeInterval'
                budget:
                  $ref: '#/components/schemas/publicCreateSpendCapRequestBudget'
                comment:
                  type: string
                  description: A reference comment for transaction. Optional.
              additionalProperties: true
        required: true
      tags:
      - SpendCap
  /rmp/mgmt/v1/platforms/{platform_id}/ad-accounts/{ad_account_id}/spend-caps/{spend_cap_id}:
    get:
      summary: ReadSpendCap
      description: Read a spend cap of an ad account.
      operationId: RmpManagementApi_ReadSpendCap
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicReadSpendCapResponse'
        '400':
          description: Bad request. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '404':
          description: Not found. One or more required resources do not exist.You can see the details in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '500':
          description: Internal server error. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
      parameters:
      - name: platform_id
        description: Identifier of the platform who requests management api. It is passed as a path parameter.
        in: path
        required: true
        schema:
          type: string
      - name: ad_account_id
        description: AdAccount id.
        in: path
        required: true
        schema:
          type: string
      - name: spend_cap_id
        description: Id of the spend cap to be retrieved.
        in: path
        required: true
        schema:
          type: string
      tags:
      - SpendCap
    put:
      summary: UpdateSpendCap
      description: Update a spend cap of an ad account.
      operationId: RmpManagementApi_UpdateSpendCap
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicUpdateSpendCapResponse'
        '400':
          description: Bad request. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '404':
          description: Not found. One or more required resources do not exist.You can see the details in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
        '500':
          description: Internal server error. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicRepresentedError'
      parameters:
      - name: platform_id
        description: Identifier of the platform who requests management api. It is passed as a path parameter.
        in: path
        required: true
        schema:
          type: string
      - name: ad_account_id
        description: AdAccount id.
        in: path
        required: true
        schema:
          type: string
      - name: spend_cap_id
        description: Spend Cap id.
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                spend_cap:
                  $ref: '#/components/schemas/UpdateSpendCapRequestSpendCapParams'
              additionalProperties: true
        required: true
      tags:
      - SpendCap
components:
  schemas:
    publicReadSpendCapResponse:
      type: object
      properties:
        spend_cap:
          $ref: '#/components/schemas/v1SpendCap'
      additionalProperties: true
    publicCreateSpendCapResponse:
      type: object
      properties:
        spend_cap:
          $ref: '#/components/schemas/v1SpendCap'
      additionalProperties: true
    commonErrorCategory:
      type: string
      enum:
      - DEFAULT_ERROR_CATEGORY
      - INPUT_VALIDATION
      - CHARACTER_LIMIT_EXCEEDED
      - TIMESTAMP_MISMATCH
      - FEATURE_NOT_ALLOWED
      - REINVITE_NOT_ALLOWED
      - LAST_OWNER_REVOKE_NOT_ALLOWED
      - LAST_OWNER_DELETE_NOT_ALLOWED
      - SSO_USER_JOIN_REQUEST_NOT_ALLOWED
      - MFA_VERIFICATION_FAILED
      - INSUFFICIENT_SPENDING_LIMIT
      - AD_ACCOUNT_ALREADY_OWNED
      - INSUFFICIENT_WALLET_BALANCE
      - INSUFFICIENT_SPEND_CAP_BUDGET
      - MAX_SPEND_CAP_COUNT_REACHED
      - MAX_CAMPAIGNS_COUNT_PER_SPEND_CAP_REACHED
      - MAX_CAMPAIGN_COUNT_REACHED
      - MODIFY_ARCHIVED_CAMPAIGN_NOT_ALLOWED
      - INVALID_CAMPAIGN_STATUS_FOR_ARCHIVE
      - INVALID_MANAGED_CPT_CAMPAIGN_SCHEDULE
      - INACTIVE_AD_ACCOUNT
      - DUPLICATE_AUDIENCE
      - INVALID_RESERVED_TIME_LINE_ITEM_SCHEDULE
      - EXCEED_MAX_IMAGE_SIZE
      - MAX_LABEL_COUNT_REACHED
      - MAX_LABEL_VALUE_COUNT_REACHED
      - MAX_LABEL_VALUE_RELATIONSHIP_COUNT_REACHED
      - PLATFORM_INSIGHT_UNAVAILABLE
      - MAX_CUSTOM_TARGETING_KEY_COUNT_REACHED
      - INVALID_CUSTOM_TARGETING
      default: DEFAULT_ERROR_CATEGORY
      title: "- INPUT_VALIDATION: INPUT_VALIDATION: reserved for 1 ~ 99\n - TIMESTAMP_MISMATCH: TIMESTAMP_MISSMATCH: reserved for 100 ~ 199\n - FEATURE_NOT_ALLOWED: General policy: 1000 ~ 1999\n - REINVITE_NOT_ALLOWED: User policy: 2000 ~ 2999\n - INSUFFICIENT_SPENDING_LIMIT: Account policy: 3000 ~ 3999\nThis policy includes ad manager account, ad account, and wallet related policies\n - MAX_CAMPAIGN_COUNT_REACHED: Campaign policy: 4000 ~ 4999\n - INVALID_RESERVED_TIME_LINE_ITEM_SCHEDULE: Returned when a RESERVED_TIME line item's schedule overlaps an existing enabled RD booking on the same inventory.\n - EXCEED_MAX_IMAGE_SIZE: Asset policy: 5000 ~ 5999\n - MAX_LABEL_COUNT_REACHED: Labeling policy: 6000 ~ 6999\n - PLATFORM_INSIGHT_UNAVAILABLE: Insight metric policy: 7000 ~ 7999\n - MAX_CUSTOM_TARGETING_KEY_COUNT_REACHED: Custom Targeting policy: 8000 ~ 8999"
    UpdateSpendCapRequestSpendCapParams:
      type: object
      properties:
        title:
          type: string
          description: Title of spend cap.
        schedule:
          $ref: '#/components/schemas/rmpcommonTimeInterval'
        budget:
          $ref: '#/components/schemas/UpdateSpendCapRequestSpendCapParamsBudget'
        status:
          $ref: '#/components/schemas/UpdateSpendCapRequestSpendCapParamsSpendCapStatus'
        comment:
          type: string
          description: A reference comment for transaction. Optional.
        updated_at:
          type: string
          format: date-time
          description: Updated timestamp. This should match the updated timestamp updated_at of the spend cap, which is able to check with ReadSpendCap API.
      additionalProperties: true
    RepresentedErrorDetail:
      type: object
      properties:
        type:
          type: string
          description: The type of the metadata.
        category:
          $ref: '#/components/schemas/commonErrorCategory'
        metadata:
          type: object
          description: The metadata of the responded error.
          additionalProperties: true
      required:
      - type
      - category
      additionalProperties: true
    rmpcommonMoneyMicro:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/rmpcommonCurrency'
        amount_micro:
          type: string
          format: int64
          description: Amount in micro unit. (e.g., 1234 means 0.001234)
      description: 'A monetary amount in a specific currency; the unit is micro at fixed point value for accurate accumulation operation.

        For example, `{"currency": "USD", "amount_micro": "1234"}` means $0.001234.'
      required:
      - currency
      - amount_micro
      additionalProperties: true
    UpdateSpendCapRequestSpendCapParamsSpendCapStatus:
      type: string
      enum:
      - UNKNOWN_SPEND_CAP_STATUS
      - ACTIVE
      - INACTIVE
      default: UNKNOWN_SPEND_CAP_STATUS
      description: The only status that a user can update to is INACTIVE or ACTIVE.
    UpdateSpendCapRequestSpendCapParamsBudget:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/UpdateSpendCapRequestSpendCapParamsBudgetPeriod'
        amount:
          $ref: '#/components/schemas/rmpcommonMoneyMicro'
      description: 'Budget is the SpendCap-specific budget shape. Intentionally

        separate from common.Budget (used by campaigns) so the

        Period enum can carry MONTHLY without leaking the value to

        campaign surfaces. The handler rejects any period change

        relative to the stored cap; only amount may be updated.'
      additionalProperties: true
    UpdateSpendCapRequestSpendCapParamsBudgetPeriod:
      type: string
      enum:
      - UNKNOWN_PERIOD
      - DAILY
      - WEEKLY
      - TOTAL
      default: UNKNOWN_PERIOD
      description: 'Numeric ordering groups the recurring kinds together

        (DAILY=1, WEEKLY=2, MONTHLY=3) with TOTAL=4 as the

        non-recurring case. Public mgmt access is REST/JSON-only

        and proto-JSON encodes enums by name, so the legacy

        binary numbering of common.Budget.Period is not relevant.'
    publicCreateSpendCapRequestBudgetPeriod:
      type: string
      enum:
      - UNKNOWN_PERIOD
      - DAILY
      - WEEKLY
      - TOTAL
      default: UNKNOWN_PERIOD
      description: 'Numeric ordering groups the recurring kinds together

        (DAILY=1, WEEKLY=2, MONTHLY=3) with TOTAL=4 as the

        non-recurring case. Public mgmt access is REST/JSON-only

        and proto-JSON encodes enums by name, so the legacy binary

        numbering of common.Budget.Period is not relevant here.'
    publicListSpendCapsResponse:
      type: object
      properties:
        spend_caps:
          type: array
          items:
            $ref: '#/components/schemas/v1SpendCap'
          description: List of spend caps.
      additionalProperties: true
    v1SpendCapMetadata:
      type: object
      properties:
        reference:
          type: string
          description: To store reference information about the SpendCap.
      additionalProperties: true
    v1SpendCap:
      type: object
      properties:
        id:
          type: string
          description: "The id of the SpendCap.\n must be left unset for the SpendCap creation request.\n must be set for the update request."
        title:
          type: string
          description: A descriptive name of the SpendCap.
        ad_account_id:
          type: string
          description: "The id of the AdAccount that owns this SpendCap.\n it is mcm platform specific ad account id.\n value and format can vary according to each mcm platform."
        currency:
          $ref: '#/components/schemas/rmpcommonCurrency'
        schedule:
          $ref: '#/components/schemas/rmpcommonTimeInterval'
        budget:
          $ref: '#/components/schemas/rmpcommonMoneyMicro'
        applied_ad_spending:
          $ref: '#/components/schemas/rmpcommonMoneyMicro'
        status:
          $ref: '#/components/schemas/v1SpendCapSpendCapStatus'
        metadata:
          $ref: '#/components/schemas/v1SpendCapMetadata'
        created_at:
          type: string
          format: date-time
          description: "Created timestamp.\n API user should not touch this field; it is set internally."
        updated_at:
          type: string
          format: date-time
          description: Updated timestamp. It is set internally.
      description: Definition of Spend Cap.
      additionalProperties: true
    rmpcommonCurrency:
      type: string
      enum:
      - UNKNOWN_CURRENCY
      - USD
      - KRW
      - JPY
      - EUR
      - GBP
      - SEK
      - INR
      - THB
      - IDR
      - CNY
      - CAD
      - RUB
      - BRL
      - SGD
      - HKD
      - AUD
      - PLN
      - DKK
      - VND
      - MYR
      - PHP
      - TRY
      - VES
      - AED
      - CHF
      default: UNKNOWN_CURRENCY
      description: "Currency enumerates available currencies.\n\n - UNKNOWN_CURRENCY: Unknown currency.\n - USD: US Dollar.\n - KRW: Korean Won.\n - JPY: Japanese Yen.\n - EUR: EU Euro.\n - GBP: British Pound.\n - SEK: Swedish Krona.\n - INR: India Rupee.\n - THB: Thailand Baht.\n - IDR: Indonesia Rupiah.\n - CNY: China Yuan.\n - CAD: Canada Dollar.\n - RUB: Russia Ruble.\n - BRL: Brazil Real.\n - SGD: Singapore Dollar.\n - HKD: Hong Kong Dollar.\n - AUD: Autrailia Dollar.\n - PLN: Poland Zloty.\n - DKK: Denmark Krone.\n - VND: Viet Nam Dong.\n - MYR: Malaysia Ringgit.\n - PHP: Philippines Peso.\n - TRY: Turkey Lira.\n - VES: Venezuela Bolívar Soberano.\n - AED: United Arab Emirates Dirham.\n - CHF: Swiss Franc."
    v1SpendCapSpendCapStatus:
      type: string
      enum:
      - UNKNOWN_SPEND_CAP_STATUS
      - SCHEDULED
      - INACTIVE
      - ACTIVE
      - ENDED
      - DEPLETED
      - ERROR
      default: UNKNOWN_SPEND_CAP_STATUS
      description: " - SCHEDULED: The SpendCap is not in an Active state due to an unexpected error case\n Similar to the Scheduled state of a campaign, the SpendCap is in a “reserved” state because its period has not yet started.\n - INACTIVE: The status when the user manually changes the SpendCap from Active to Inactive.\n - ACTIVE: The SpendCap is in an Active state. As long as the amount is not depleted, the mapped campaigns can remain Active and serve ads without issues\n - ENDED: One of the cases where the SpendCap is no longer Active because its defined period has ended.\n - DEPLETED: The SpendCap has reached its allocated amount (0 remaining). As a result, the mapped campaigns can no longer remain active and ad serving stops, even though the period itself has not yet ended.\n - ERROR: Error state. The campaign state does not belong to any states above."
    publicUpdateSpendCapResponse:
      type: object
      properties:
        spend_cap:
          $ref: '#/components/schemas/v1SpendCap'
      additionalProperties: true
    rmpcommonTimeInterval:
      type: object
      properties:
        start:
          type: string
          format: date-time
          description: Start time in RFC3339 format, e.g. "2017-04-01T12:34:56+00:00"
        end:
          type: string
          format: date-time
          description: End time in RFC3339 format, e.g. "2017-05-01-T21:09:08+00:00"
      description: 'Campaign''s interval with start and end timestamps in RFC3339 format.

        The Campaign will conceptually run during [schedule_start, schedule_end] inclusively.

        It is highly recommended that schedule.start is set to UTC corresponding to the beginning of the day (00:00:00), and schedule.end is set to UTC corresponding to the end of the day (23:59:59) both in the ad account''s timezone.

        If you want to set no end date, make sure your platform supports no end date setting and just leave schedule_end blank.'
      required:
      - start
      additionalProperties: true
    publicRepresentedError:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: The status code, which should be an enum value of google.rpc.Code.(https://developers.google.com/actions-center/reference/grpc-api/status_codes)
        message:
          type: string
          description: The detailed message of responded error.
        details:
          type: array
          items:
            $ref: '#/components/schemas/RepresentedErrorDetail'
          description: The detailed information of responded error. Please refer to the error category section in guides for more detailed information.(https://rmp-docs.moloco.com/docs/management-api-error-categories)
      title: Overridden from grpc status(https://github.com/grpc/grpc/blob/master/src/proto/grpc/status/status.proto)
      required:
      - code
      - message
      - details
      additionalProperties: true
    publicCreateSpendCapRequestBudget:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/publicCreateSpendCapRequestBudgetPeriod'
        amount:
          $ref: '#/components/schemas/rmpcommonMoneyMicro'
      description: 'Budget is the SpendCap-specific budget shape. Intentionally

        separate from common.Budget (used by campaigns) so the Period

        enum can carry MONTHLY without leaking the value to campaign

        surfaces.'
      additionalProperties: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header
    Bearer:
      type: apiKey
      description: Note that the bearer authentication has been deprecated. Please refer [API and SSO Credential Management](https://mcm-docs.moloco.com/docs/api-key-and-sso-secret-generation) section to use API-key instead.
      name: Authorization
      in: header
x-readme:
  explorer-enabled: false