Marqeta Account Rewards API

openapi: 3.0.3
info:
  contact:
    email: support@marqeta.com
    name: Marqeta
  description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta.
  termsOfService: https://www.marqeta.com/api-terms
  title: Core accepted countries Account Rewards API
  version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- description: '// Conditional snippet for beta or internal content

    include::../../maturity-admonition-banner.adoc[]


    Use the `/credit/accounts/{account_token}/rewards` endpoint to create a one-time reward on a <</core-api/credit-accounts, credit account>>.


    Creating a reward triggers the creation of a <</core-api/credit-account-journal-entries, journal entry>> belonging to the `REWARD` group.

    For more on reward journal entries, see <</developer-guides/about-credit-account-journal-entries#_rewards, Rewards>> in the About Credit Account Journal Entries guide.


    For the reward programs that are associated with a reward policy on a bundle, see <</developer-guides/about-credit-reward-accounts/, About Credit Reward Accounts>> and <</core-api/credit-reward-global-configurations/, Reward Global Configurations>>.'
  name: Account Rewards
paths:
  /accounts/{account_token}/rewards:
    post:
      description: Create a reward for an existing credit account.
      operationId: createReward
      parameters:
      - description: 'Unique identifier of the credit account for which you want to create a reward.


          Send a `GET` request to `/credit/accounts` to retrieve existing credit account tokens.'
        explode: false
        in: path
        name: account_token
        required: true
        schema:
          type: string
          x-allowableValues: Existing account token
        style: simple
      requestBody:
        content:
          application/json:
            example:
              account_token: my_account_token_12
              amount: 20
              created_time: 2023-09-03 22:53:57.895000+00:00
              currency_code: USD
              description: $20 reward
              token: my_rewards_token1234
              type: CASH_BACK
              updated_time: 2023-09-03 22:53:57.895000+00:00
            schema:
              $ref: '#/components/schemas/RewardCreateReq'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                account_token: my_account_token_12
                amount: 20
                created_time: 2023-09-03 22:53:57.895000+00:00
                currency_code: USD
                description: $20 reward
                token: my_rewards_token1234
                type: CASH_BACK
                updated_time: 2023-09-03 22:53:57.895000+00:00
              schema:
                $ref: '#/components/schemas/RewardResponse'
          description: Newly created reward
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      security:
      - zionToken: []
      summary: Create account reward
      tags:
      - Account Rewards
components:
  schemas:
    RewardResponse:
      properties:
        account_token:
          description: Unique identifier of the account on which the reward exists.
          maxLength: 36
          type: string
        amount:
          description: Amount of the reward.
          minimum: 0
          type: number
        applied_to_amount:
          description: 'Total amount to which a percentage reward method is applied (for example, if a 3% reward is applied to 100, then `100` is the `applied_to_amount` value).


            This field is not applicable for a flat fee method.


            Returned for auto-cash back reward types only.'
          type: number
        created_time:
          description: Date and time when the reward was created on Marqeta's credit platform, in UTC.
          format: date-time
          type: string
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        description:
          description: Description of the reward.
          type: string
        method:
          $ref: '#/components/schemas/Method'
        note:
          description: Additional information about the reward.
          type: string
        token:
          description: 'Unique identifier of the reward.


            If in the `detail_object`, unique identifier of the detail object.'
          type: string
        type:
          $ref: '#/components/schemas/RewardType'
        updated_time:
          description: Date and time when the reward was last updated on Marqeta's credit platform, in UTC.
          format: date-time
          type: string
        value:
          description: 'Value of the percentage or flat amount.


            Returned for auto-cash back reward types only.'
          type: number
      required:
      - amount
      - created_time
      - currency_code
      - description
      - token
      - type
      - updated_time
      type: object
    Method:
      description: 'Method, either a flat amount or a percentage.


        *NOTE:*

        Only `FLAT` is currently supported.'
      enum:
      - PERCENTAGE
      - FLAT
      type: string
    RewardCreateReq:
      properties:
        amount:
          description: Amount of the reward.
          exclusiveMinimum: true
          minimum: 0
          type: number
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        description:
          description: Description of the reward.
          maxLength: 255
          type: string
        forced:
          description: 'Allows you to force the creation of a reward on an account.


            By default, reward creation is not permitted for accounts with a status of `SUSPENDED` or `TERMINATED` if more than 90 days have passed since the status transition.'
          type: boolean
        note:
          description: Additional information about the reward.
          maxLength: 255
          type: string
        token:
          description: Unique identifier of the reward.
          maxLength: 36
          pattern: (?!^ +$)^.+$
          type: string
      required:
      - amount
      - currency_code
      - description
      - type
      type: object
    CurrencyCode:
      default: USD
      description: Valid three-digit link:https://www.iso.org/iso-4217-currency-codes.html[ISO 4217 currency code, window="_blank"].
      enum:
      - USD
      type: string
    RewardType:
      description: Type of reward.
      enum:
      - AUTO_CASH_BACK
      - CASH_BACK
      - STATEMENT_CREDIT
      type: string
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
      type: object
  securitySchemes:
    mqAppAndAccessToken:
      scheme: basic
      type: http