openapi: 3.1.0
info:
  title: Amazon Advertising Ad Groups Refunds API
  description: The Amazon Advertising API enables programmatic management of advertising campaigns on Amazon. It provides access to Sponsored Products, Sponsored Brands, and Sponsored Display campaigns across various marketplaces. Developers can create, manage, and optimize advertising campaigns, access reporting data, and manage budgets and targeting through this REST API.
  version: '1.0'
  contact:
    name: Amazon Advertising Support
    url: https://advertising.amazon.com/API/docs/en-us
  termsOfService: https://advertising.amazon.com/terms
servers:
- url: https://advertising-api.amazon.com
  description: North America
- url: https://advertising-api-eu.amazon.com
  description: Europe
- url: https://advertising-api-fe.amazon.com
  description: Far East
- url: https://advertising-api-test.amazon.com
  description: Test/Sandbox
security:
- bearerAuth: []
tags:
- name: Refunds
  description: Process refunds on captured charges
paths:
  /refunds:
    post:
      operationId: createRefund
      summary: Amazon Create a Refund
      description: Creates a refund for a previously captured charge.
      tags:
      - Refunds
      parameters:
      - $ref: '#/components/parameters/PayDate'
      - $ref: '#/components/parameters/PayRegion'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRefundRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '400':
          description: Bad request
  /refunds/{refundId}:
    get:
      operationId: getRefund
      summary: Amazon Get Refund Details
      description: Returns details about the specified refund.
      tags:
      - Refunds
      parameters:
      - name: refundId
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/PayDate'
      - $ref: '#/components/parameters/PayRegion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '404':
          description: Not found
components:
  schemas:
    CreateRefundRequest:
      type: object
      required:
      - chargeId
      - refundAmount
      properties:
        chargeId:
          type: string
        refundAmount:
          $ref: '#/components/schemas/Price'
        softDescriptor:
          type: string
          maxLength: 16
    Price:
      type: object
      required:
      - amount
      - currencyCode
      properties:
        amount:
          type: string
        currencyCode:
          type: string
    StatusDetails:
      type: object
      properties:
        state:
          type: string
        reasonCode:
          type: string
        reasonDescription:
          type: string
    Refund:
      type: object
      properties:
        refundId:
          type: string
        chargeId:
          type: string
        refundAmount:
          $ref: '#/components/schemas/Price'
        softDescriptor:
          type: string
        statusDetails:
          $ref: '#/components/schemas/StatusDetails'
        creationTimestamp:
          type: string
          format: date-time
  parameters:
    PayDate:
      name: x-amz-pay-date
      in: header
      required: true
      schema:
        type: string
        format: date-time
    IdempotencyKey:
      name: x-amz-pay-idempotency-key
      in: header
      required: true
      schema:
        type: string
    PayRegion:
      name: x-amz-pay-region
      in: header
      required: true
      schema:
        type: string
        enum:
        - us
        - eu
        - jp
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token from Login with Amazon
externalDocs:
  description: Amazon Advertising API Documentation
  url: https://advertising.amazon.com/API/docs/en-us/reference/api-overview