Emporix Coupon Redemption API

openapi: 3.2.0
info:
  title: Emporix Coupon Redemption API
  version: ''
  contact:
    email: documentation@emporix.com
  description: 'Operations tagged Coupon Redemption across 2 of this provider''s published API definitions: emporix-coupon-openapi.yml, emporix-coupon-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2: []
tags:
- name: Coupon Redemption
paths:
  /coupon/{tenant}/coupons/{code}/redemptions:
    parameters:
    - $ref: '#/components/parameters/coupon_code'
    - $ref: '#/components/parameters/trait_tenant'
    get:
      summary: Retrieving a list of redemptions by criteria
      tags:
      - Coupon Redemption
      responses:
        '200':
          description: List of redemptions
          headers:
            Items-Count:
              $ref: '#/components/headers/Total-Count'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/redemptions'
              examples:
                RedemptionList:
                  $ref: '#/components/examples/redemptionList'
        '400':
          $ref: '#/components/responses/trait_queryable_400'
        '401':
          $ref: '#/components/responses/trait_unauthorized_401'
        '403':
          $ref: '#/components/responses/trait_restricted_403'
        '404':
          $ref: '#/components/responses/trait_notFound_404'
        '500':
          $ref: '#/components/responses/trait_internal_500'
      description: Retrieves a list of redemptions by the specified criteria. Supports sorting and paging.
      operationId: GET-coupon-list-coupon-redemptions
      parameters:
      - $ref: '#/components/parameters/trait_sortable_sort'
      - $ref: '#/components/parameters/trait_paged_pageNumber'
      - $ref: '#/components/parameters/trait_paged_pageSize'
      - $ref: '#/components/parameters/trait_countable_totalCount'
      - $ref: '#/components/parameters/trait_queryable_q'
      security:
      - OAuth2:
        - coupon.coupon_manage
    post:
      summary: Redeeming the coupon by creating a redemption
      tags:
      - Coupon Redemption
      responses:
        '201':
          description: 'The coupon has been redeemed and the redemption has been successfully created.

            '
          content:
            application/json:
              examples:
                CreateRedemption:
                  $ref: '#/components/examples/createRedemptionResponse'
              schema:
                $ref: '#/components/schemas/resource-location'
        '400':
          $ref: '#/components/responses/trait_queryable_400'
        '401':
          $ref: '#/components/responses/trait_unauthorized_401'
        '403':
          $ref: '#/components/responses/trait_restricted_403'
        '404':
          $ref: '#/components/responses/trait_notFound_404'
        '409':
          $ref: '#/components/responses/trait_conflict_409'
        '500':
          $ref: '#/components/responses/trait_internal_500'
      description: 'Invalidate the coupon based on its validity scope. Redemption is not possible when the coupon has exceeded its maximum

        number allowed redemptions. To be redeemed a coupon needs to be already valid and not expired yet.

        ***


        ### Additional scopes info

        * The `coupon.coupon_redeem_on_behalf` scope is only required if the service should use the customer identification specified in the request body (`customerNumber` attribute) instead of the one associated with current authentication token.'
      operationId: POST-coupon-invalidate-coupon
      requestBody:
        content:
          application/json:
            examples:
              CouponRedemption:
                $ref: '#/components/examples/couponRedemption'
            schema:
              $ref: '#/components/schemas/redemption-creation'
        required: true
      security:
      - OAuth2:
        - coupon.coupon_redeem_on_behalf
    servers:
    - url: https://api.emporix.io
  /coupon/{tenant}/coupons/{code}/redemptions/{id}:
    parameters:
    - $ref: '#/components/parameters/redemption_id'
    - $ref: '#/components/parameters/coupon_code'
    - $ref: '#/components/parameters/trait_tenant'
    get:
      summary: Retrieving a coupon redemption
      tags:
      - Coupon Redemption
      responses:
        '200':
          description: The coupon redemption has been successfully retrieved.
          content:
            application/json:
              examples:
                Redemption:
                  $ref: '#/components/examples/redemption'
              schema:
                $ref: '#/components/schemas/redemption'
        '400':
          $ref: '#/components/responses/trait_queryable_400'
        '401':
          $ref: '#/components/responses/trait_unauthorized_401'
        '403':
          $ref: '#/components/responses/trait_restricted_403'
        '404':
          $ref: '#/components/responses/trait_notFound_404'
        '500':
          $ref: '#/components/responses/trait_internal_500'
      description: 'Retrieves a single redemption.

        ***


        ### Additional scopes info

        * The `coupon.coupon_manage` scope is required for accessing any redemption.

        * The `coupon.coupon_redeem` scope is required for accessing only redemption created by current user.

        * The `coupon.coupon_redeem_on_behalf` scope is only required if the service should use the customer identification specified in the request body (`customerNumber`attribute) instead of the one associated with current authentication token.'
      operationId: GET-coupon-retrieve-coupon-redemption
      parameters:
      - $ref: '#/components/parameters/customer_number'
      security:
      - OAuth2:
        - coupon.coupon_manage
        - coupon.coupon_redeem
        - coupon.coupon_redeem_on_behalf
    delete:
      summary: Deleting a coupon redemption
      tags:
      - Coupon Redemption
      responses:
        '204':
          description: 'A redemption with the provided code has been successfully deleted.

            '
        '400':
          $ref: '#/components/responses/trait_queryable_400'
        '401':
          $ref: '#/components/responses/trait_unauthorized_401'
        '403':
          $ref: '#/components/responses/trait_restricted_403'
        '404':
          $ref: '#/components/responses/trait_notFound_404'
        '500':
          $ref: '#/components/responses/trait_internal_500'
      description: Deletes a previously created redemption.
      operationId: DELETE-coupon-remove-coupon-redemption
      security:
      - OAuth2:
        - coupon.coupon_manage
    servers:
    - url: https://api.emporix.io
components:
  parameters:
    redemption_id:
      name: id
      in: path
      required: true
      schema:
        type: string
    trait_sortable_sort:
      name: sort
      in: query
      description: 'The list of comma-separated properties used to sort the results.

        By default, the column values are sorted in ascending order.

        Can either be in the form of fieldName or fieldName:asc,fieldName:desc.

        If you want to sort by localized attributes, you must use the following form:

        fieldName.language or fieldName.language:asc,fieldName.language:desc.

        '
      schema:
        type: string
    trait_queryable_q:
      name: q
      in: query
      description: 'The simple query criteria based on available fields to limit returned results or a set of modified documents.

        '
      schema:
        type: string
    coupon_code:
      name: code
      in: path
      required: true
      schema:
        type: string
      description: Code of a coupon.
    trait_paged_pageNumber:
      name: pageNumber
      in: query
      description: 'The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.

        The number of the first page is 1.

        '
      schema:
        default: 1
        minimum: 1
        type: integer
    trait_countable_totalCount:
      name: totalCount
      in: query
      description: 'This parameter requests to return the total number of object in the collection fulfilling

        the criteria together with the response. This number will be returned in the ''items-count''

        header.

        '
      schema:
        type: boolean
    trait_paged_pageSize:
      name: pageSize
      in: query
      description: 'The number of documents being retrieved on the page.

        '
      schema:
        default: 16
        minimum: 1
        type: integer
    customer_number:
      name: customerNumber
      in: query
      required: false
      description: 'Customer number (ID) of customer on behalf of which we request coupon information.

        Needed only in case of retrieving coupon eligible for other customer than the caller.

        '
      schema:
        type: string
    trait_tenant:
      name: tenant
      in: path
      required: true
      description: 'The tenant that the caller is acting upon.


        Please note that this value is always lowercase.

        '
      schema:
        minLength: 3
        maxLength: 16
        type: string
  examples:
    createRedemptionResponse:
      value:
        id: 6058912da917ae6f360f2557
    redemption:
      value:
        id: 6429b8fdf8fd8e0001df1617
        code: 10-OFF
        customerNumber: '61443563'
        orderTotal:
          amount: 299.3
          currency: USD
        discount:
          amount: 29.93
          currency: USD
        redeemedAt: '2023-04-02T17:18:53.701Z'
    couponRedemption:
      value:
        customerNumber: CustomerId
        orderTotal:
          amount: 1090
          currency: EUR
        discount:
          amount: 5
          currency: EUR
    redemptionList:
      value:
      - id: 6429b8fdf8fd8e0001df1617
        code: 10-OFF
        customerNumber: '61443563'
        orderTotal:
          amount: 299.3
          currency: USD
        discount:
          amount: 29.93
          currency: USD
        redeemedAt: '2023-04-02T17:18:53.701Z'
      - id: 642aa7f5f8fd8e0001df161b
        code: 10-OFF
        customerNumber: '61443563'
        orderTotal:
          amount: 369.07
          currency: USD
        discount:
          amount: 36.91
          currency: USD
        redeemedAt: '2023-04-03T10:18:29.233Z'
  schemas:
    resource-location:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the link.
        yrn:
          type: string
          description: Identifier of the link in the system's notation.
    currency-amount:
      type: object
      title: Money amount
      description: Defines an amount in a specific currency.
      properties:
        amount:
          type: number
          default: 0
          minimum: 0
          description: Total amount in the specified currency.
        currency:
          type: string
          default: USD
          pattern: ^[A-Z]{3}$
          description: 'ISO 4217 currency code, e.g.: USD, EUR, CHF.'
    redemption:
      type: object
      title: Coupon Redemption
      description: Defines a coupon redemption response.
      allOf:
      - $ref: '#/components/schemas/redemption-creation'
      properties:
        id:
          description: Unique identifier of the redemption.
          type: string
        redeemedAt:
          description: Timestamp of the redemption.
          type: string
          format: date-time
    redemption-creation:
      type: object
      title: Coupon Redemption Request
      description: Defines a coupon redemption request payload that affects a coupon instance.
      properties:
        orderCode:
          description: Code of the associated order.
          type: string
        customerNumber:
          type: string
          description: The customer Id of the user, e.g. C0123456789. Can be specified only if coupon.coupon_redeem_on_behalf scope is present.
        legalEntityId:
          type: string
          description: The id of the legal entity to which customer is assigned. When customer is assigned to many legal entities then he can redeem the same coupon separately for each legal entity.
        orderTotal:
          allOf:
          - $ref: '#/components/schemas/currency-amount'
          - description: The amount of the purchase.
        discount:
          allOf:
          - $ref: '#/components/schemas/currency-amount'
          - description: The absolute amount of the granted discount.
      required:
      - orderTotal
      - discount
    redemptions:
      type: array
      items:
        $ref: '#/components/schemas/redemption'
  responses:
    trait_restricted_403:
      description: Access forbidden. The caller is not allowed to access this resource.
      content:
        application/json:
          schema:
            title: error
            description: Schema for API specified errors.
            example:
              status: 403
              message: Not allowed to access this resource
              type: insufficient_permissions
            type: object
            properties:
              status:
                minimum: 100
                maximum: 599
                description: Original HTTP error code, should be consistent with the response HTTP code.
                type: integer
              type:
                pattern: '[a-z]+[a-z_]*[a-z]+'
                description: Classification of the error type, lower case with underscore eg validation_failure.
                type: string
              message:
                description: Descriptive error message for debugging.
                type: string
            required:
            - status
            - type
          examples:
            Example 1:
              value:
                type: insufficient_permissions
                status: 403
                message: Insufficient permissions to retrieve the coupon with Id MW2023_7
    trait_notFound_404:
      description: 'The requested resource does not exist.

        '
      content:
        application/json:
          schema:
            title: error
            description: Schema for API specified errors.
            example:
              status: 404
              message: The requested URI does not map to a single element resource.
              type: element_resource_non_existing
            type: object
            properties:
              status:
                minimum: 100
                maximum: 599
                description: Original HTTP error code, should be consistent with the response HTTP code.
                type: integer
              type:
                pattern: '[a-z]+[a-z_]*[a-z]+'
                description: Classification of the error type, lower case with underscore eg validation_failure.
                type: string
              message:
                description: Descriptive error message for debugging.
                type: string
            required:
            - status
            - type
          examples:
            Not found:
              value:
                type: resource_not_found
                status: 404
                message: Coupon with code MW2023_72 not found.
    trait_internal_500:
      description: 'Some server side error occurred.

        '
      content:
        application/json:
          schema:
            title: error
            description: Schema for API specified errors.
            example:
              status: 500
              message: Something went wrong while processing the request. Please contact the administrator.
              type: internal_service_error
            type: object
            properties:
              status:
                minimum: 100
                maximum: 599
                description: Original HTTP error code, should be consistent with the response HTTP code.
                type: integer
              type:
                pattern: '[a-z]+[a-z_]*[a-z]+'
                description: Classification of the error type, lower case with underscore eg validation_failure.
                type: string
              message:
                description: Descriptive error message for debugging.
                type: string
              details:
                description: List of problems causing this error.
                type: array
                items:
                  title: errorDetail
                  description: Schema for specific error cause.
                  type: object
                  properties:
                    field:
                      description: A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.
                      type: string
                    type:
                      pattern: '[a-z]+[a-z_]*[a-z]+'
                      description: Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.
                      type: string
                    message:
                      description: Descriptive error detail message for debugging.
                      type: string
                    moreInfo:
                      type: string
                      description: Link to documentation to investigate further and finding support for error detail.
                  required:
                  - type
            required:
            - status
            - type
    trait_queryable_400:
      description: Request syntactically incorrect. Details of the error are included in the response payload.
      content:
        application/json:
          schema:
            title: error
            description: Schema for API specified errors.
            example:
              status: 400
              message: There are validation problems, see details section for more information.
              type: validation_violation
              details:
              - field: q
                message: not a valid query
                type: invalid_query_parameter
            type: object
            properties:
              status:
                minimum: 100
                maximum: 599
                description: Original HTTP error code, should be consistent with the response HTTP code.
                type: integer
              type:
                pattern: '[a-z]+[a-z_]*[a-z]+'
                description: Classification of the error type, lower case with underscore eg validation_failure.
                type: string
              message:
                description: Descriptive error message for debugging.
                type: string
              details:
                description: List of problems causing this error.
                type: array
                items:
                  title: errorDetail
                  description: Schema for specific error cause.
                  type: object
                  properties:
                    field:
                      description: A bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific.
                      type: string
                    type:
                      pattern: '[a-z]+[a-z_]*[a-z]+'
                      description: Classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.
                      type: string
                    message:
                      description: Descriptive error detail message for debugging.
                      type: string
                    moreInfo:
                      type: string
                      description: Link to documentation to investigate further and finding support for error detail.
                  required:
                  - type
            required:
            - status
            - type
          examples:
            Bad request:
              value:
                type: validation_violation
                status: 400
                message: The request violates validation constraints.
                details:
                - type: missing_payload
                  message: Empty payload was sent
                  moreInfo: ''
    trait_conflict_409:
      description: 'Creation failed because there was a conflict with another resource. Details of the error are included in the response payload.

        '
      content:
        application/json:
          schema:
            title: error
            description: Schema for API specified errors.
            example:
              status: 409
              message: The requested resource could not be created due to server-side validation.
              type: conflict_resource
            type: object
            properties:
              status:
                minimum: 100
                maximum: 599
                description: Original HTTP error code, should be consistent with the response HTTP code.
                type: integer
              type:
                pattern: '[a-z]+[a-z_]*[a-z]+'
                description: Classification of the error type, lower case with underscore eg validation_failure.
                type: string
              message:
                description: Descriptive error message for debugging.
                type: string
            required:
            - status
            - type
          examples:
            Conflict:
              value:
                type: conflict_resource
                status: 409
                message: Duplicate Coupon 'MW2023_7' on tenant 'tenantname'
    trait_unauthorized_401:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            Unauthorized:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
  headers:
    Total-Count:
      required: false
      description: 'The total number of objects that fulfil the criteria.

        '
      schema:
        type: integer
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            coupon.coupon_read: Needed to read coupons.
            coupon.coupon_manage: Needed to manage coupons.
            coupon.coupon_redeem: Needed to redeem coupons.
            coupon.coupon_redeem_on_behalf: Needed to redeem coupons on behalf of another customer.
x-refined-from:
- emporix-coupon-openapi.yml
- emporix-coupon-openapi.yml