openapi: 3.1.0
info:
  title: ENDVR Client API
  version: 0.2.0-draft
  summary: Run Pro Deals on any e-commerce platform.
  description: |
    Server-to-server API for brands that run Pro Deals on an e-commerce platform other than Shopify:
    read Pro Deals and their codes, confirm the codes are live, report the orders that used them,
    keep the product catalog in sync and receive webhooks.

    **Draft.** This contract is published for review and is not served yet. Paths, fields and limits
    can change until `/v1` is released; after that, `/v1` only changes additively.

    Guides: https://docs.endvr.io/docs/api
  contact:
    name: ENDVR Developers
    url: https://docs.endvr.io
servers:
  - url: https://api.endvr.io/v1
    description: Production (test and live keys)
security:
  - integrationKey: []
tags:
  - name: Connection
    description: The connection an integration key belongs to.
  - name: Pro Deals
    description: The brand's Pro Deals and the codes behind them.
  - name: Redemptions
    description: Orders that used a Pro Deal code.
  - name: Catalog
    description: The brand's products, keyed by the brand's own ids.
  - name: Webhooks
    description: Where ENDVR sends events for this connection, and the events it sends.
paths:
  /connection:
    get:
      tags: [Connection]
      operationId: getConnection
      summary: Get the connection
      description: |
        The brand, platform, mode and status of the connection the key belongs to. Call it first to check a key.
      responses:
        "200":
          description: The connection.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connection"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /pro-deals:
    get:
      tags: [Pro Deals]
      operationId: listProDeals
      summary: List Pro Deals
      description: The brand's Pro Deals, newest first.
      parameters:
        - name: status
          in: query
          description: Only Pro Deals in this status.
          schema:
            $ref: "#/components/schemas/ProDealStatus"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of Pro Deals.
          content:
            application/json:
              schema:
                type: object
                required: [data, nextCursor]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProDeal"
                  nextCursor:
                    $ref: "#/components/schemas/NextCursor"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /pro-deals/{id}:
    get:
      tags: [Pro Deals]
      operationId: getProDeal
      summary: Get a Pro Deal
      parameters:
        - $ref: "#/components/parameters/ProDealId"
      responses:
        "200":
          description: The Pro Deal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProDeal"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /pro-deals/{id}/codes:
    get:
      tags: [Pro Deals]
      operationId: listProDealCodes
      summary: List codes
      description: |
        The Pro Deal's codes and their state. For a Pro Deal with `codeSource: generated`, these are the codes to
        create in your store as single-use discount codes. Send `Accept: text/csv` for one code per line.
      parameters:
        - $ref: "#/components/parameters/ProDealId"
        - name: status
          in: query
          description: Only codes in this state.
          schema:
            $ref: "#/components/schemas/CodeStatus"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of codes.
          content:
            application/json:
              schema:
                type: object
                required: [data, nextCursor]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Code"
                  nextCursor:
                    $ref: "#/components/schemas/NextCursor"
            text/csv:
              schema:
                type: string
              example: |
                code
                PRO-7KQ2-XM4D
                PRO-9TRB-2HNC
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags: [Pro Deals]
      operationId: uploadProDealCodes
      summary: Upload your own codes
      description: |
        For a Pro Deal with `codeSource: uploaded`: add codes you created in your store. Up to 100 codes per call;
        a code already on the Pro Deal comes back as `duplicate`.
      parameters:
        - $ref: "#/components/parameters/ProDealId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [codes]
              properties:
                codes:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    minLength: 3
                    maxLength: 64
            example:
              codes: [ACME-PRO-0001, ACME-PRO-0002]
      responses:
        "200":
          $ref: "#/components/responses/BatchResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
  /pro-deals/{id}/codes/confirm:
    post:
      tags: [Pro Deals]
      operationId: confirmProDealCodes
      summary: Confirm the codes are live
      description: |
        Tells ENDVR the codes work in your store. ENDVR then releases the Pro Deal to associates, who can claim
        their codes in the ENDVR app. Safe to repeat; confirm again after adding codes.
      parameters:
        - $ref: "#/components/parameters/ProDealId"
      responses:
        "200":
          description: The Pro Deal after the confirmation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProDeal"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /redemptions:
    get:
      tags: [Redemptions]
      operationId: listRedemptions
      summary: List redemptions
      description: Redemptions reported with this key's mode, most recently updated first.
      parameters:
        - name: proDealId
          in: query
          schema:
            type: string
        - name: code
          in: query
          schema:
            type: string
        - name: orderId
          in: query
          schema:
            type: string
        - name: updatedSince
          in: query
          description: Only redemptions updated at or after this time.
          schema:
            type: string
            format: date-time
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of redemptions.
          content:
            application/json:
              schema:
                type: object
                required: [data, nextCursor]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/RedemptionRecord"
                  nextCursor:
                    $ref: "#/components/schemas/NextCursor"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Redemptions]
      operationId: reportRedemptions
      summary: Report redemptions
      description: |
        Up to 100 orders that used a Pro Deal code. A redemption is unique on `(code, orderId)`: sending it again
        with a newer `updatedAt` updates it, and an equal or older one comes back as `duplicate`, so retries are
        safe. An associate's next code opens once their current code is reported.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [redemptions]
              properties:
                redemptions:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: "#/components/schemas/Redemption"
            example:
              redemptions:
                - code: PRO-7KQ2-XM4D
                  orderId: "10042"
                  orderAmount: "129.90"
                  currency: USD
                  processedAt: "2026-11-17T14:03:00Z"
                  status: paid
                  updatedAt: "2026-11-17T14:03:00Z"
      responses:
        "200":
          $ref: "#/components/responses/BatchResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Invalid"
        "429":
          $ref: "#/components/responses/RateLimited"
  /catalog/products:
    get:
      tags: [Catalog]
      operationId: listProducts
      summary: List products
      parameters:
        - name: updatedSince
          in: query
          description: Only products changed at or after this time.
          schema:
            type: string
            format: date-time
        - name: includeArchived
          in: query
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of products.
          content:
            application/json:
              schema:
                type: object
                required: [data, nextCursor]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProductRecord"
                  nextCursor:
                    $ref: "#/components/schemas/NextCursor"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Catalog]
      operationId: upsertProducts
      summary: Upsert products
      description: |
        Creates or replaces up to 100 products, keyed by your own product ids. A product sent again replaces the
        stored one, variants included; an archived product sent again is restored.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [products]
              properties:
                products:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: "#/components/schemas/Product"
            example:
              products:
                - id: "prod_1001"
                  title: Trail Runner 2
                  url: https://shop.example.com/products/trail-runner-2
                  imageUrl: https://shop.example.com/images/trail-runner-2.jpg
                  variants:
                    - id: "var_1001_42"
                      sku: TR2-BLK-42
                      title: Black / 42
                      price: "159.00"
                      currency: USD
      responses:
        "200":
          $ref: "#/components/responses/BatchResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Invalid"
  /catalog/products/{id}:
    get:
      tags: [Catalog]
      operationId: getProduct
      summary: Get a product
      parameters:
        - $ref: "#/components/parameters/ProductId"
      responses:
        "200":
          description: The product, archived or not.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductRecord"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Catalog]
      operationId: archiveProduct
      summary: Archive a product
      description: Hides the product from new campaigns. Upsert it again to restore it.
      parameters:
        - $ref: "#/components/parameters/ProductId"
      responses:
        "204":
          description: Archived.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /webhooks:
    get:
      tags: [Webhooks]
      operationId: getWebhook
      summary: Get the webhook endpoint
      responses:
        "200":
          description: The webhook configuration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Webhook"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Webhooks]
      operationId: putWebhook
      summary: Set the webhook endpoint
      description: |
        Sets where ENDVR sends events. The signing secret is returned when the endpoint is first set and when
        `rotateSecret` is true, and never again. After a rotation, events carry signatures from both secrets for
        24 hours.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, events]
              properties:
                url:
                  type: string
                  format: uri
                  description: An HTTPS URL.
                events:
                  type: array
                  minItems: 1
                  items:
                    $ref: "#/components/schemas/WebhookEventType"
                rotateSecret:
                  type: boolean
                  default: false
            example:
              url: https://shop.example.com/endvr/webhooks
              events: [code.deactivate, pro_deal.ended]
      responses:
        "200":
          description: The webhook configuration, with `secret` when it was just created or rotated.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Webhook"
                  - type: object
                    properties:
                      secret:
                        type: string
                        description: The signing secret. Present only right after it was created or rotated.
                        examples: [whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Invalid"
  /webhooks/test:
    post:
      tags: [Webhooks]
      operationId: sendTestWebhook
      summary: Send a test event
      description: Sends a signed event of the chosen type with sample data to the configured endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type]
              properties:
                type:
                  $ref: "#/components/schemas/WebhookEventType"
            example:
              type: code.deactivate
      responses:
        "200":
          description: The delivery attempt.
          content:
            application/json:
              schema:
                type: object
                required: [delivered, statusCode]
                properties:
                  delivered:
                    type: boolean
                    description: True when your endpoint answered 2xx.
                  statusCode:
                    type: [integer, "null"]
                    description: Your endpoint's HTTP status; null when it could not be reached.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
webhooks:
  code.deactivate:
    post:
      tags: [Webhooks]
      operationId: codeDeactivateEvent
      summary: code.deactivate
      description: |
        A code must stop working in your store: disable or delete the discount code. Sent when the brand removes an
        associate from a Pro Deal or the associate leaves a targeted store. Codes already used are not sent.
      parameters:
        - $ref: "#/components/parameters/WebhookId"
        - $ref: "#/components/parameters/WebhookTimestamp"
        - $ref: "#/components/parameters/WebhookSignature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/WebhookEnvelope"
                - type: object
                  properties:
                    type:
                      const: code.deactivate
                    data:
                      type: object
                      required: [proDealId, code, reason]
                      properties:
                        proDealId:
                          type: string
                        code:
                          type: string
                        reason:
                          type: string
                          enum: [associate_removed, associate_left_store]
            example:
              type: code.deactivate
              timestamp: "2026-11-17T15:20:11Z"
              data:
                proDealId: 6730f1c2a9d4e5b6c7d8e9f0
                code: PRO-7KQ2-XM4D
                reason: associate_left_store
      responses:
        "200":
          description: Answer any 2xx once the event is stored; anything else is retried.
  pro_deal.ended:
    post:
      tags: [Webhooks]
      operationId: proDealEndedEvent
      summary: pro_deal.ended
      description: |
        The Pro Deal ended. Disable its codes that were not used. No `code.deactivate` is sent for them.
      parameters:
        - $ref: "#/components/parameters/WebhookId"
        - $ref: "#/components/parameters/WebhookTimestamp"
        - $ref: "#/components/parameters/WebhookSignature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/WebhookEnvelope"
                - type: object
                  properties:
                    type:
                      const: pro_deal.ended
                    data:
                      type: object
                      required: [proDealId, endedAt]
                      properties:
                        proDealId:
                          type: string
                        endedAt:
                          type: string
                          format: date-time
            example:
              type: pro_deal.ended
              timestamp: "2026-12-31T23:59:59Z"
              data:
                proDealId: 6730f1c2a9d4e5b6c7d8e9f0
                endedAt: "2026-12-31T23:59:59Z"
      responses:
        "200":
          description: Answer any 2xx once the event is stored; anything else is retried.
components:
  securitySchemes:
    integrationKey:
      type: http
      scheme: bearer
      description: |
        A brand integration key, created by an Owner or Admin in Brand Settings › Integrations and shown once.
        `endvr_ik_test_…` keys write test data that is never billed; `endvr_ik_live_…` keys are live.
  headers:
    RateLimit:
      description: The remaining quota and the seconds until it resets, as `limit=…, remaining=…, reset=…`.
      schema:
        type: string
  parameters:
    ProDealId:
      name: id
      in: path
      required: true
      description: Pro Deal id.
      schema:
        type: string
        examples: [6730f1c2a9d4e5b6c7d8e9f0]
    ProductId:
      name: id
      in: path
      required: true
      description: Your own product id.
      schema:
        type: string
        examples: [prod_1001]
    Cursor:
      name: cursor
      in: query
      description: The `nextCursor` of the previous page. Omit for the first page.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: Items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    WebhookId:
      name: webhook-id
      in: header
      required: true
      description: Unique id of the event; the same on every retry. Use it to ignore duplicates.
      schema:
        type: string
        examples: [msg_2pQ7d1Xk9aLr4Bz]
    WebhookTimestamp:
      name: webhook-timestamp
      in: header
      required: true
      description: Seconds since the Unix epoch when this attempt was signed.
      schema:
        type: string
        examples: ["1794928811"]
    WebhookSignature:
      name: webhook-signature
      in: header
      required: true
      description: Space-separated `v1,<base64 HMAC-SHA256>` signatures (Standard Webhooks).
      schema:
        type: string
        examples: ["v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4="]
  schemas:
    NextCursor:
      type: [string, "null"]
      description: Pass it as `cursor` for the next page; `null` on the last page.
    Money:
      type: string
      pattern: '^\d+(\.\d{1,4})?$'
      description: A decimal amount as a string, in the currency named next to it.
      examples: ["129.90"]
    Currency:
      type: string
      pattern: "^[A-Z]{3}$"
      description: ISO 4217 code.
      examples: [USD]
    Mode:
      type: string
      enum: [test, live]
      description: "`test` for data written with a test key, `live` otherwise."
    Connection:
      type: object
      required: [brandId, brandName, platform, mode, status, lastEventAt]
      properties:
        brandId:
          type: string
        brandName:
          type: string
        platform:
          type: string
          description: The e-commerce platform chosen when the key was created.
          examples: [woocommerce]
        mode:
          $ref: "#/components/schemas/Mode"
        status:
          type: string
          enum: [connected, waiting_first_event, error, paused]
          description: |
            `waiting_first_event` until the first call that writes data; `error` when webhooks keep failing;
            `paused` when the brand paused the connection in the portal.
        lastEventAt:
          type: [string, "null"]
          format: date-time
      example:
        brandId: 64b7f0c2a1d2e3f4a5b6c7d8
        brandName: Acme Outdoor
        platform: woocommerce
        mode: test
        status: connected
        lastEventAt: "2026-11-17T14:03:05Z"
    ProDealStatus:
      type: string
      enum: [draft, scheduled, live, paused, finished]
    CodeStatus:
      type: string
      enum: [available, assigned, used, deactivated]
      description: |
        `available`: not claimed yet; `assigned`: claimed by an associate; `used`: reported in a redemption;
        `deactivated`: must not work any more (see the `code.deactivate` and `pro_deal.ended` events).
    ProDeal:
      type: object
      required:
        [
          id,
          title,
          status,
          discount,
          codesPerAssociate,
          codeSource,
          codesReady,
          codes,
          startsAt,
          endsAt,
        ]
      properties:
        id:
          type: string
        title:
          type: string
        status:
          $ref: "#/components/schemas/ProDealStatus"
        discount:
          type: object
          required: [type, value]
          properties:
            type:
              type: string
              enum: [percentage]
            value:
              type: number
              description: The percentage off, for example 40 for 40%.
        codesPerAssociate:
          type: integer
          minimum: 1
          maximum: 5
          description: How many codes each associate can claim, one after the other.
        codeSource:
          type: string
          enum: [generated, uploaded]
          description: "`generated`: ENDVR generates the codes for you to create; `uploaded`: you upload your own."
        codesReady:
          type: boolean
          description: True once you confirmed the codes are live in your store.
        codes:
          type: object
          description: How many codes are in each state.
          required: [total, available, assigned, used, deactivated]
          properties:
            total:
              type: integer
            available:
              type: integer
            assigned:
              type: integer
            used:
              type: integer
            deactivated:
              type: integer
        startsAt:
          type: [string, "null"]
          format: date-time
        endsAt:
          type: [string, "null"]
          format: date-time
      example:
        id: 6730f1c2a9d4e5b6c7d8e9f0
        title: Winter Pro Deal
        status: live
        discount:
          type: percentage
          value: 40
        codesPerAssociate: 2
        codeSource: generated
        codesReady: true
        codes:
          total: 500
          available: 412
          assigned: 61
          used: 25
          deactivated: 2
        startsAt: "2026-11-01T00:00:00Z"
        endsAt: "2026-12-31T23:59:59Z"
    Code:
      type: object
      required: [code, status, assignedAt, usedAt, deactivatedAt]
      properties:
        code:
          type: string
        status:
          $ref: "#/components/schemas/CodeStatus"
        assignedAt:
          type: [string, "null"]
          format: date-time
        usedAt:
          type: [string, "null"]
          format: date-time
        deactivatedAt:
          type: [string, "null"]
          format: date-time
      example:
        code: PRO-7KQ2-XM4D
        status: used
        assignedAt: "2026-11-10T09:12:00Z"
        usedAt: "2026-11-17T14:03:00Z"
        deactivatedAt: null
    Redemption:
      type: object
      required:
        [code, orderId, orderAmount, currency, processedAt, status, updatedAt]
      properties:
        code:
          type: string
          description: The Pro Deal code applied to the order.
        orderId:
          type: string
          description: The order id in your store.
        orderAmount:
          $ref: "#/components/schemas/Money"
          description: |
            The order's line items after discounts, without tax or shipping, in the order's currency. The first
            amount ENDVR receives for an order is the one billed.
        currency:
          $ref: "#/components/schemas/Currency"
        processedAt:
          type: string
          format: date-time
          description: When the order was placed.
        status:
          type: string
          enum: [paid, cancelled, voided]
        updatedAt:
          type: string
          format: date-time
          description: When the order last changed in your store. The newest version of a redemption wins.
        refunds:
          type: array
          description: Stored for reference, never billed.
          items:
            type: object
            required: [amount, processedAt]
            properties:
              amount:
                $ref: "#/components/schemas/Money"
              processedAt:
                type: string
                format: date-time
    RedemptionRecord:
      allOf:
        - $ref: "#/components/schemas/Redemption"
        - type: object
          required: [id, proDealId, mode, receivedAt]
          properties:
            id:
              type: string
            proDealId:
              type: string
            mode:
              $ref: "#/components/schemas/Mode"
            receivedAt:
              type: string
              format: date-time
              description: When ENDVR first received this redemption.
      example:
        id: rdm_5Kq2Xm4D7tRb
        proDealId: 6730f1c2a9d4e5b6c7d8e9f0
        mode: live
        code: PRO-7KQ2-XM4D
        orderId: "10042"
        orderAmount: "129.90"
        currency: USD
        processedAt: "2026-11-17T14:03:00Z"
        status: paid
        updatedAt: "2026-11-17T14:03:00Z"
        refunds: []
        receivedAt: "2026-11-17T14:03:05Z"
    Product:
      type: object
      required: [id, title, variants]
      properties:
        id:
          type: string
          description: Your own product id.
        title:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
          description: The product page in your store.
        imageUrl:
          type: string
          format: uri
        variants:
          type: array
          minItems: 1
          maxItems: 250
          items:
            type: object
            required: [id, price, currency]
            properties:
              id:
                type: string
                description: Your own variant id.
              sku:
                type: string
              title:
                type: string
              price:
                $ref: "#/components/schemas/Money"
              currency:
                $ref: "#/components/schemas/Currency"
    ProductRecord:
      allOf:
        - $ref: "#/components/schemas/Product"
        - type: object
          required: [archived, updatedAt]
          properties:
            archived:
              type: boolean
            updatedAt:
              type: string
              format: date-time
      example:
        id: prod_1001
        title: Trail Runner 2
        url: https://shop.example.com/products/trail-runner-2
        imageUrl: https://shop.example.com/images/trail-runner-2.jpg
        variants:
          - id: var_1001_42
            sku: TR2-BLK-42
            title: Black / 42
            price: "159.00"
            currency: USD
        archived: false
        updatedAt: "2026-11-15T10:00:00Z"
    WebhookEventType:
      type: string
      enum: [code.deactivate, pro_deal.ended]
    Webhook:
      type: object
      required: [url, events, lastDeliveryAt, failingSince]
      properties:
        url:
          type: [string, "null"]
          format: uri
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
        lastDeliveryAt:
          type: [string, "null"]
          format: date-time
          description: The last successful delivery.
        failingSince:
          type: [string, "null"]
          format: date-time
          description: Set while deliveries keep failing; null when healthy.
    WebhookEnvelope:
      type: object
      required: [type, timestamp, data]
      description: The body of every event, following Standard Webhooks.
      properties:
        type:
          $ref: "#/components/schemas/WebhookEventType"
        timestamp:
          type: string
          format: date-time
          description: When the event happened.
        data:
          type: object
    ItemResult:
      type: object
      required: [index, result]
      properties:
        index:
          type: integer
          description: Position of the item in the request, from 0.
        result:
          type: string
          enum: [accepted, duplicate, rejected]
          description: |
            `accepted`: stored or updated; `duplicate`: nothing changed (already stored, same or older version);
            `rejected`: not stored, see `reason`.
        reason:
          type: string
          description: Why the item was rejected.
          examples: [unknown_code]
    Problem:
      type: object
      description: RFC 9457 problem details.
      required: [type, title, status, requestId]
      properties:
        type:
          type: string
          format: uri
          description: A stable URI for the kind of error, linking to its documentation.
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        requestId:
          type: string
          description: Quote it when you contact ENDVR.
        errors:
          type: array
          description: On validation errors, one entry per invalid field.
          items:
            type: object
            required: [path, message]
            properties:
              path:
                type: string
                examples: ["redemptions[0].orderAmount"]
              message:
                type: string
  responses:
    BatchResult:
      description: One result per item, in request order.
      content:
        application/json:
          schema:
            type: object
            required: [results]
            properties:
              results:
                type: array
                items:
                  $ref: "#/components/schemas/ItemResult"
          example:
            results:
              - index: 0
                result: accepted
              - index: 1
                result: rejected
                reason: unknown_code
    Unauthorized:
      description: Missing, unknown or revoked key.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://docs.endvr.io/docs/api/errors#unauthorized
            title: Unauthorized
            status: 401
            detail: The integration key is missing, unknown or revoked.
            requestId: req_8kq2xm4d7trb
    NotFound:
      description: Not found for this brand.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://docs.endvr.io/docs/api/errors#not-found
            title: Not found
            status: 404
            requestId: req_2hnc9trb7kq2
    Conflict:
      description: The resource is not in a state that allows this call.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://docs.endvr.io/docs/api/errors#conflict
            title: Conflict
            status: 409
            detail: This Pro Deal generates its codes; uploading codes is only for uploaded Pro Deals.
            requestId: req_4bz1xk9alr4b
    Invalid:
      description: The body failed validation.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://docs.endvr.io/docs/api/errors#validation-failed
            title: Validation failed
            status: 422
            requestId: req_7trb2hnc8kq2
            errors:
              - path: redemptions[0].orderAmount
                message: must be a decimal string such as "129.90"
    RateLimited:
      description: Too many requests. Wait for `Retry-After` seconds.
      headers:
        Retry-After:
          schema:
            type: integer
        RateLimit:
          $ref: "#/components/headers/RateLimit"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://docs.endvr.io/docs/api/errors#rate-limited
            title: Too many requests
            status: 429
            requestId: req_9alr4bz1xk2p
