Crevio Discounts API

openapi: 3.2.0
info:
  title: Crevio API V1 Discounts API
  version: 1.0.0
  description: 'API for the Crevio creator platform — a multi-tenant SaaS for digital product sales.

    Uses snake_case keys following Stripe conventions. All resource IDs are string IDs (e.g., "prod_abc123").


    Authentication is a bearer token: `Authorization: Bearer $CREVIO_API_KEY`.

    List endpoints are cursor-paginated with `limit` and `starting_after`.

    Writes accept an `Idempotency-Key` header and are safe to retry.


    Every response carries IETF RateLimit headers (`RateLimit`, `RateLimit-Policy`) so a client can

    self-throttle, and `Retry-After` on a 429. The quota is 600 requests per minute per credential.


    The API is versioned in the URL path (`/v1`). Nothing is removed without in-band warning: a

    deprecated operation is marked `"deprecated": true` here and serves `Deprecation` (RFC 9745),

    `Sunset` (RFC 8594) and `Link; rel="deprecation"` headers for at least six months before it

    stops answering. See https://crevio.co/docs/developer/guides/versioning.'
  contact:
    email: support@crevio.co
    name: Crevio Support
    url: https://crevio.co/docs
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://crevio.co/legal/terms-of-service
servers:
- url: https://api.crevio.co/v1
  description: Production
security:
- ApiKey: []
tags:
- name: Discounts
  description: Discount code management
paths:
  /discounts:
    get:
      summary: List discounts
      description: Returns a list of discounts for the current account
      operationId: listDiscounts
      x-crevio-sdk-method: list
      tags:
      - Discounts
      security:
      - ApiKey: []
      parameters:
      - name: status
        in: query
        description: Filter by discount status. `inactive` codes were turned off; an `active` code past its `redeem_by` still reports `active`.
        schema:
          type: string
          enum:
          - active
          - inactive
      - name: query
        in: query
        description: Search by discount code
        schema:
          type: string
      - name: starting_after
        in: query
        description: Cursor for pagination — the ID of the last item in the previous page
        schema:
          type: string
      - name: limit
        in: query
        description: Items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: List of discounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_Discount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.discounts.list({});\n\n  console.log(result);\n}\n\nrun();"
    post:
      summary: Create discount
      description: Creates a new discount code
      operationId: createDiscount
      x-crevio-sdk-method: create
      tags:
      - Discounts
      security:
      - ApiKey: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Makes this write safe to retry: a repeat with the same key replays the first response instead of creating a second resource. Scoped to the account, remembered for 24 hours; reusing a key with a different payload is an error.'
        schema:
          type: string
          maxLength: 255
        example: 1f7a4c2e-3b19-4a6d-9f0c-2ac81b5d7e33
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscountRequest'
      responses:
        '201':
          description: Discount created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.discounts.create({});\n\n  console.log(result);\n}\n\nrun();"
  /discounts/{id}:
    get:
      summary: Get discount
      description: Returns a specific discount
      operationId: getDiscount
      x-crevio-sdk-method: get
      tags:
      - Discounts
      security:
      - ApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        description: The resource ID (e.g., "prod_abc123") or slug (e.g., "my-product")
        schema:
          type: string
      responses:
        '200':
          description: Discount details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.discounts.get({\n    id: \"<id>\",\n  });\n\n  console.log(result);\n}\n\nrun();"
    patch:
      summary: Update discount
      description: Updates an existing discount
      operationId: updateDiscount
      x-crevio-sdk-method: update
      tags:
      - Discounts
      security:
      - ApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        description: The resource ID (e.g., "prod_abc123") or slug (e.g., "my-product")
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscountRequest'
      responses:
        '200':
          description: Discount updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.discounts.update({\n    id: \"<id>\",\n    discountRequest: {},\n  });\n\n  console.log(result);\n}\n\nrun();"
    delete:
      summary: Delete discount
      description: Deletes a discount
      operationId: deleteDiscount
      x-crevio-sdk-method: delete
      tags:
      - Discounts
      security:
      - ApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        description: The resource ID (e.g., "prod_abc123") or slug (e.g., "my-product")
        schema:
          type: string
      responses:
        '200':
          description: Discount deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: ask
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.discounts.delete({\n    id: \"<id>\",\n  });\n\n  console.log(result);\n}\n\nrun();"
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: forbidden
              message: You do not have permission to perform this action
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: bad_request
              message: The request was malformed or contained invalid parameters
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: authentication_required
              message: You did not provide an API key.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: resource_missing
              message: The requested resource was not found
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    TooManyRequests:
      description: 'Rate limit exceeded — 600 requests per minute per owner on the free tier: every API key and OAuth token one person holds on an account shares one budget, and the account''s team keys share another. Retry after the number of seconds in `Retry-After`.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: rate_limit_exceeded
              message: Too many requests. Please retry later.
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: api_error
              code: internal_error
              message: An unexpected error occurred
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    UnprocessableEntity:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: validation_error
              code: validation_failed
              message: Email is required
              errors:
                email:
                - can't be blank
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
  schemas:
    DeleteResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        deleted:
          type: boolean
          enum:
          - true
      required:
      - id
      - object
      - deleted
    Discount:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
        discount_type:
          type: string
          enum:
          - percentage
          - fixed
        code:
          type: string
        amount_off:
          type:
          - integer
          - 'null'
        duration:
          type: string
          enum:
          - forever
          - once
          - repeating
        duration_in_months:
          type:
          - integer
          - 'null'
        max_redemptions:
          type:
          - integer
          - 'null'
        times_redeemed:
          type: integer
        starts_at:
          type:
          - string
          - 'null'
          format: date-time
        redeem_by:
          type:
          - string
          - 'null'
          format: date-time
        minimum_amount:
          type:
          - integer
          - 'null'
        once_per_customer:
          type: boolean
        first_order_only:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        percent_off:
          type:
          - number
          - 'null'
          format: double
        currency:
          type:
          - string
          - 'null'
      required:
      - id
      - object
      - status
      - discount_type
      - code
      - amount_off
      - duration
      - duration_in_months
      - max_redemptions
      - times_redeemed
      - starts_at
      - redeem_by
      - minimum_amount
      - once_per_customer
      - first_order_only
      - created_at
      - updated_at
      - percent_off
      - currency
    ListResponse_Discount:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        has_more:
          type: boolean
        url:
          type: string
      required:
      - object
      - data
      - has_more
      - url
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - api_error
              - invalid_request_error
              - validation_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            errors:
              type: object
            doc_url:
              type: string
          required:
          - type
          - message
      required:
      - error
    DiscountRequest:
      type: object
      properties:
        code:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
          description: '`inactive` turns the code off at once and checkout rejects it; `active` turns it back on. Leaves `redeem_by` and the code''s products unchanged.'
        discount_type:
          type: string
          enum:
          - percentage
          - fixed
        amount_off:
          type:
          - integer
          - 'null'
        percent_off:
          type:
          - number
          - 'null'
        currency:
          type:
          - string
          - 'null'
        duration:
          type: string
          enum:
          - forever
          - once
          - repeating
        duration_in_months:
          type:
          - integer
          - 'null'
        starts_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the code becomes usable. Checkout rejects it before this time; omit it to make the code usable right away. For a sale that starts later, create the discount now with `starts_at` set rather than scheduling its creation.
        redeem_by:
          type:
          - string
          - 'null'
          format: date-time
          description: When the code stops being usable. Must be after `starts_at` and in the future whenever it is set. To end a code now, set `status` to `inactive`.
        max_redemptions:
          type:
          - integer
          - 'null'
          minimum: 1
          description: How many live orders can use the code, across all customers. Test purchases don't count. The limit set at creation also stays on the Stripe coupon, so raising it later has no effect past that number.
        minimum_amount:
          type:
          - integer
          - 'null'
          minimum: 1
          description: Smallest order subtotal, in cents before the discount, that can use the code. Requires `currency`; an order in another currency can't use the code. `null` removes it.
        once_per_customer:
          type: boolean
          description: Each customer can use the code on one live order.
        first_order_only:
          type: boolean
          description: Only customers with no earlier live paid order from this business can use the code. Free orders and test purchases don't count as earlier orders.
        price_variants:
          type: array
          items:
            type: string
  headers:
    Sunset:
      description: Present only on a deprecated operation. HTTP-date (RFC 8594) after which the operation stops responding. Always at least six months after `Deprecation`.
      schema:
        type: string
        examples:
        - Thu, 01 Oct 2026 00:00:00 GMT
    RequestId:
      description: Unique id for this request. Quote it when reporting a problem.
      schema:
        type: string
        examples:
        - 8fe045fe-cb8a-4407-a44d-5df60385e522
    DeprecationLink:
      description: Present only on a deprecated operation. `<url>; rel="deprecation"` pointing at the migration notes.
      schema:
        type: string
        examples:
        - <https://crevio.co/docs/developer/guides/versioning>; rel="deprecation"
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        examples:
        - 11
    Deprecation:
      description: Present only on a deprecated operation. Structured-field date (RFC 9745) — `@` followed by the Unix timestamp at which the operation became deprecated.
      schema:
        type: string
        examples:
        - '@1775001600'
    RateLimit:
      description: 'Remaining quota for the current window, as an IETF structured field: `"default";r=<remaining>;t=<seconds until reset>`.'
      schema:
        type: string
        examples:
        - '"default";r=596;t=11'
    RateLimitPolicy:
      description: 'The quota this credential is subject to: `"default";q=<requests>;w=<window seconds>`.'
      schema:
        type: string
        examples:
        - '"default";q=600;w=60'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key in the format: Bearer {api_token}'
externalDocs:
  description: Crevio developer documentation
  url: https://crevio.co/docs/developer
x-mint:
  mcp:
    enabled: true
x-api-lifecycle:
  current_major_version: v1
  versioning_scheme: URL path
  deprecation_policy_url: https://crevio.co/docs/developer/guides/versioning
  minimum_notice_days: 183
  deprecation_headers:
  - Deprecation
  - Sunset
  - Link